home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Magnum One
/
Magnum One (Mid-American Digital) (Disc Manufacturing).iso
/
d16
/
snap402i.arc
/
SNAP.DOC
< prev
next >
Wrap
Text File
|
1990-09-07
|
183KB
|
4,880 lines
SNAP!
Documentation and Development System
for dBASE, Clipper, FoxPro
and Similar Systems
Written by Walter J. Kennamer 74025,514
┌─────────┐
┌─────┴───┐ │ (tm)
──│ │o │──────────────────
│ ┌─────┴╨──┐ │ Association of
│ │ │─┘ Shareware
└───│ o │ Professionals
──────│ ║ │────────────────────
└────╨────┘ MEMBER
License
Copyright (c) 1986-1989 Walter J. Kennamer. All Rights
Reserved.
You are free to use, copy and distribute SNAP! providing that:
NO FEE IS CHARGED FOR USE, COPYING OR DISTRIBUTION.
IT IS NOT MODIFIED IN ANY WAY.
THIS DOCUMENTATION FILE (UNMODIFIED) ACCOMPANIES ALL COPIES.
This program is provided AS IS without any warranty, expressed
or implied, including but not limited to fitness for a
particular purpose.
dBASE II, dBASE III, dBASE IV are trademarks of Ashton-Tate.
Clipper is a trademark of Nantucket Software. FoxBASE,
FoxBASE+ and FoxPro are trademarks of Fox Software, Inc. UNIX
is a trademark of AT&T.
Table of Contents
Overview . . . . . . . . . . . . . . . . . . . . . . . . 4
Dbase Dialects . . . . . . . . . . . . . . . . . . . . 5
Registration Fee . . . . . . . . . . . . . . . . . . . 5
Getting Started . . . . . . . . . . . . . . . . . . . . . 6
Basic Operation . . . . . . . . . . . . . . . . . . . 6
A Tour of the SNAP! Screens . . . . . . . . . . . . . 7
Author and Copyright Holder . . . . . . . . . . . . . 7
Paths . . . . . . . . . . . . . . . . . . . . . . . . 7
Saving and Restoring Default Choices . . . . . . . . . 9
Abbreviations . . . . . . . . . . . . . . . . . . . . 9
Status Reports . . . . . . . . . . . . . . . . . . . . 10
Searching the Program Tree . . . . . . . . . . . . . . 10
dBASE Version? . . . . . . . . . . . . . . . . . . . . 11
Ignoring Drive Designations . . . . . . . . . . . . . 11
Printing SNAP! Documentation . . . . . . . . . . . . . 11
Using a Mouse . . . . . . . . . . . . . . . . . . . . 13
SNAP! Commands . . . . . . . . . . . . . . . . . . . . . 14
Macros . . . . . . . . . . . . . . . . . . . . . . . . 14
Indirect References . . . . . . . . . . . . . . . . . 16
SNAPCODE--Fake Program Statements . . . . . . . . . . 16
Program Narratives . . . . . . . . . . . . . . . . . . 17
Other SNAP! Directives . . . . . . . . . . . . . . . . 17
Source Code Formatting Options . . . . . . . . . . . . . 19
File Headings . . . . . . . . . . . . . . . . . . . . 19
Indentation . . . . . . . . . . . . . . . . . . . . . 20
Capitalization . . . . . . . . . . . . . . . . . . . . 21
Key Word Expansion and Compression . . . . . . . . . . 22
Suppressing Blank Lines and Comments . . . . . . . . . 23
Key Words File . . . . . . . . . . . . . . . . . . . . 23
Reports and Outputs . . . . . . . . . . . . . . . . . . . 26
Controlling the Printer . . . . . . . . . . . . . . . 26
Tree Structure Diagram . . . . . . . . . . . . . . . . 27
File List . . . . . . . . . . . . . . . . . . . . . . 28
Data Dictionary . . . . . . . . . . . . . . . . . . . 28
Index File Summary . . . . . . . . . . . . . . . . . . 30
Format File Summary . . . . . . . . . . . . . . . . . 31
Report Form Summary . . . . . . . . . . . . . . . . . 31
Label Form Summary . . . . . . . . . . . . . . . . . . 32
Procedure File Summary . . . . . . . . . . . . . . . . 32
Other Summary Reports . . . . . . . . . . . . . . . . 32
Variable Cross-Reference Report . . . . . . . . . . . 32
LNK and MAKE files . . . . . . . . . . . . . . . . . . 36
Batch Files . . . . . . . . . . . . . . . . . . . . . 37
Action Diagrams . . . . . . . . . . . . . . . . . . . 38
Source Code Printout . . . . . . . . . . . . . . . . . 41
2
Printing Without Documenting (Reprinting) . . . . . . 43
Using SNAP! in a Batch Environment . . . . . . . . . . . 44
Random Notes . . . . . . . . . . . . . . . . . . . . . . 45
Program Limitations . . . . . . . . . . . . . . . . . . . 46
Legal Coding that is Prohibited by SNAP! . . . . . . . 46
Hyphens in Filenames . . . . . . . . . . . . . . . . . 47
Continuation Lines . . . . . . . . . . . . . . . . . . 47
Multiple Procedure Files . . . . . . . . . . . . . . . 48
Suppressing Color . . . . . . . . . . . . . . . . . . 48
Change History . . . . . . . . . . . . . . . . . . . . . 49
Administrative Matters . . . . . . . . . . . . . . . . . 53
Version Numbers . . . . . . . . . . . . . . . . . . . 53
Updates and New Versions . . . . . . . . . . . . . . . 53
How to Get Support . . . . . . . . . . . . . . . . . . 53
Association of Shareware Professionals . . . . . . . . 54
Acknowledgements . . . . . . . . . . . . . . . . . . . . 55
Appendix A -- Sample Reports . . . . . . . . . . . . . . 56
Index . . . . . . . . . . . . . . . . . . . . . . . . . . 77
3
Overview
(A short note to the faithful: those of you who have used
SNAP! before may wish to turn directly to the Change History
where new features in version 4.0 are summarized.)
SNAP! makes documenting Dbase programs a snap. SNAP! is
designed to produce technical documentation for an entire
Dbase system. Its reports include:
Formatted source code listings
System summary showing lines of code, file statistics, etc.
Variable cross-reference report
Tree structure of the system. The tree optionally can also
show databases, index files, etc. used by each program.
List of all files in the system, plus a source reprint file
Data dictionary
Index file summary
Format file summary
Label form summary
Report form summary
Procedure/function file summary
BIN file summary
Memory file summary
Other files summary
Link files for Clipper applications (either PLINK86, TLINK,
MS-LINK)
Make file for Clipper applications
Action diagrams
Batch files to back up programs, databases, etc.
Batch file to move SNAP! output files back to the source
subdirectory
In addition, on each program file, SNAP! can write a heading
showing:
Program name
System name
Author and copyright notice
Which programs, procedures and function call this program
Which programs, procedures and functions this program calls
Databases used
Index files used
Formats used
Report forms used
Procedures
BIN files called or loaded
Memory files used
Date and time last modified
4
If you wish, all source code headings can also be echoed to a
separate file. Additionally, SNAP! can indent your source
code and capitalize dBASE key words to make your code easier
to read, understand and maintain.
Unlike many other Dbase documentation systems, SNAP!
documentation is system-wide. In other words, not only can it
tell you where variable X was used in a particular program, it
can cross-reference all occurrences of variable X anywhere in
the program system you are documenting. You merely enter the
"top" program file name, and SNAP! does the rest. Of course,
you may also document a single program if you wish.
Dbase Dialects
SNAP! fully supports the following dialects of the Dbase
language:
dBASE II
dBASE III
dBASE III+
dBASE IV 1.0
FoxBASE
FoxBASE+ 2.1
FoxPro 1.0
Clipper (releases through Summer '87)
In addition, SNAP! generally handles dbXL, Quicksilver and
VP-INFO programs pretty well. However, I do not guarantee
that it fully supports all features of these products.
Registration Fee
There isn't one. SNAP! can be copied and distributed freely,
as long as it is unchanged and you include this document file
unmodified. I encourage you to give copies to your friends
and co-workers, to upload them to bulletin boards, and to
leave them in bus stations.
5
Getting Started
First, make a backup copy of your program files. I have tried
to test SNAP! on a variety of hardware and software
combinations, and there shouldn't be any danger, but I would
feel awful if anyone lost program files due to some curious
combination of resident programs, unusual equipment and
sunspot activity, not to mention (gasp!) "features." SNAP!
has been around for several years now and nobody has reported
that SNAP! has ever corrupted source code, but I would hate
for you to be the first.
Basic Operation
SNAP! is very easy to use. If you accept the program's
default options, you only have to enter the following
information on the TopFile screen:
"Top" file name
System name
Author and copyright information
Paths for program, data, output and SNAP! files
If you are happy with the defaults, just enter the information
on the first screen (the System screen), press F10 to see the
main menu, then press 'B' to begin documenting your system.
The term "TopFile" (spelled and punctuated in a variety of
ways) is used throughout this documentation to mean the first
file in a system--the one first invoked.
You can press F10 to see the main menu. Its choices largely
correspond to various option screens. For example, you set
report options on the Reports Screen and there is a "Reports"
choice on the main menu.
If you don't want to use the menu, you can save a keystroke or
two by using the Alt key in combination with the menu choice
you want. For example, without pressing F10 to pop up the
menu, you can press Alt-R to see the Reports Screen, Alt-B to
Begin Documenting, Alt-Q to quit and so forth. Also, the
Ctrl-PgUp and Ctrl-PgDn keys take you to the preceding and
succeeding screens respectively.
The line at the bottom of the screen tells you which function
keys are active. You can access these functions by pressing
the function key or by pointing at the description on the
bottom of the screen with a mouse. At any point, you can
press the F1 key to receive context-sensitive help. Help is
available for each field.
6
The SNAP! system is composed of the following files:
SNAP.EXE -- main program file
SNAP.HLP -- help file
SNAP.DOC -- this documentation file
DB2WORDS.SNP -- key word file for dBASE II/FoxBASE
DB3WORDS.SNP -- key word file for dBASE III/Clipper/FoxBASE+
DB4WORDS.SNP -- key word file for dBASE IV/FoxPro
SNAPPRT.SNP -- printer definitions
filename.KEY -- key word files for third-party libraries
All of these files must be in the same subdirectory, which may
be different than the subdirectory in which your dBASE source
code files are stored.
A Tour of the SNAP! Screens
SNAP! has seven main screens on which you can select various
combinations of options:
System: Contains system-level information (system name,
author, top file name, etc.).
Report: Determines which documentation reports will be
generated.
Format: Determines source code formatting and action diagram
options in effect.
Xref: Determines what kinds of words will be in the cross-
reference.
Tree: Determines what kinds of files will be shown on the
tree diagram.
Print: Determines source code printing parameters. Other:
Other options.
The next sections highlight a few of the fields that may have
hidden mysteries.
Author and Copyright Holder
Enter the author and copyright holder in these fields. This
information is used only in the program headings, and may be
omitted if you choose not to write program headings (you make
that choice on the Format screen). If you enter either author
or holder, but not both, SNAP! assumes that they are the same.
Paths
The TopFile menu screen has four fields for path
information--the path to the source code, data, output and
SNAP! files. Your response should be a valid MS-DOS path,
with or without drive designation. It doesn't matter if you
7
omit the final backslash (e.g., C:\SNAP is valid, as is
C:\SNAP\ or \SNAP).
If the TopFile you specify cannot be found, or if the SNAP!
files are not where you say they are, SNAP! complains and will
not let you begin documentation. If the output directory does
not exist, SNAP! will create it.
If your input and output paths are different, SNAP! will not
modify your original source code files in any way. Only the
output files will contain capitalized key words, indents,
headings and so on.
On the other hand, if the source code and output paths are the
same, SNAP! adds .BAK extensions to your original input files
and creates modified output files with the original names.
For example, if one of your input programs was named EDIT.PRG,
after running SNAP! it will be called EDIT.BAK and a new,
modified EDIT.PRG will be in the directory. This scheme works
fine as long as all your input files have unique names (not
counting the extension). Otherwise, all but the last
non-unique input file will be lost (though the modified output
files will still be there). The best idea is never to direct
output to the input directory if the first eight characters of
all of your program files are not unique.
All of your source code files--including programs, format
files, report forms, memory files and so forth--must be in the
same source directory for SNAP! to find them. (Databases and
indexes can be either in the data directory or in the source
code directory.) Even if the application runs fine in
multiple subdirectories under dBASE IV, you still need to move
all program files into a single subdirectory for SNAP! If
you use explicit drive and path designations when you
reference another file, SNAP! will find it (as long as you
have not told SNAP! to ignore drive designations--see below),
but it otherwise cannot tell which subdirectory is current.
Note that SNAP! pays no attention to "SET PATH TO" statements.
SNAP! also cannot handle macro substitutions for drives or
paths.
SNAP! never modifies database, index, report form, label form
or memory files.
When SNAP! decides you are about to do something particularly
dangerous, it may require you to direct output files to a
different directory than the input files are in. Some
"dangerous" options include expanding or compressing key words
and eliminating comments from source code.
8
Saving and Restoring Default Choices
As you use SNAP!, you may wish to modify the default values
for certain fields. For example, you may want to set the
SNAP! path to \SNAP, or the author and copyright holder to
your name. Press F5 to save the current values of each field.
SNAP! will prompt you for a filename to use for the
configuration file.
When you start SNAP!, you can specify the file to use for
default values by using the /F switch on the command line.
For example, the command:
SNAP /fc:\foo\bar.baz (note: no space between '/f' and the
filename).
tells SNAP! to look for a configuration file named 'bar.baz'
in the '\foo' subdirectory on drive c:. If it cannot find it,
SNAP! will start with default values. When you save the
configuration, SNAP! uses the name you specified. If you do
not specify a file, SNAP! looks for one called CONFIG.SNP in
the current directory. If the file you specify does not have
an extension, SNAP! assumes the extension is '.SNP'. So the
order for establishing defaults is:
1. A configuration file you specify on the command line
2. CONFIG.SNP in the current subdirectory
3. SNAP! factory default values
I ordinarily save a separate configuration file for each
system I use in the same subdirectory with the system. This
is a big help for running SNAP! in batch mode (see below) and
for keeping subdirectories, filenames, etc. straight.
You can also press F6 to retrieve saved specifications.
Invoking SNAP! with the /F command-line parameter is
equivalent to entering the program, pressing F6 at the System
screen and entering a filename.
Abbreviations
In general, SNAP! is pretty good about recognizing valid dBASE
abbreviations. For example, it will properly detect that
<tab>DO <tab> WHIL<tab>
initiates a DO loop. Version 3.00 also removed the earlier
restriction on abbreviating INDEX ('SET INDE TO foo' is fine
now).
Also, if you use dBASE key words as variable names, SNAP! can
sometimes become confused. For example, if you use 'PROC' as
a variable name within a procedure file and put the statement
'PROC = FOO' within the file, SNAP! will see the 'PROC' and
think that it is initiating a new procedure. Common sense
will ordinarily avoid this problem. As always, it is a good
9
idea not to use key words in a way other than that intended by
the language, especially if you plan to compile the code;
compilers tend to be more picky about this restriction than
interpreters.
Status Reports
As SNAP! documents your programs, it updates a status screen
that tells you how much progress it has made. The screen
shows the file that SNAP! is currently documenting and the
number of lines in the file. SNAP! makes two passes through
each file--one to determine which files use or call which
other files, and one for cross-referencing variables,
formatting source code and preparing action diagrams.
In addition, if you choose any option that modifies source
code (headings, indentation, key word capitalization,
compression or expansion, etc.), or if you choose to display
the cross-reference report, SNAP! will display a more
elaborate screen indicating how many programs, databases,
indexes, format files, report forms and variables it has
found, along with the total number of program lines documented
so far, and the amount of free memory available. This screen
also shows the elapsed time since you began documentation.
Note: some people have reported that the elapsed time is
occasionally negative. This is normal. It means that your
computer is actually running faster than light. It is nothing
to be concerned about unless you have an 8087 chip, which
sometimes overheats when moving backwards in time.
If SNAP! identifies any errors during its run, it will print a
brief error message in a separate window in the upper right
corner of the screen. All error messages are also echoed to
the ERROR.DOC file.
Searching the Program Tree
SNAP! assumes that you want to document not only the TopFile,
but all programs it calls, all programs called by programs
that Top calls, and so on. In fact, SNAP! will search the
program tree for all programs, databases, index files, report
forms, format files, label forms and memory files as it
prepares system documentation. You never need to specify more
than the top program file name.
If you choose not to search the tree (you can make this choice
on the Other Options Screen), only the specific file you enter
will be documented. Thus, you can limit documentation to a
10
particular file or a branch of the program tree by varying
either the file you input as Top or the search tree parameter.
Note that SNAP! does not track "SET DEFAULT TO x" statements,
but always expects to see files with no drive designations on
the default drive and in the source file subdirectory.
dBASE Version?
On the Other Options screen, SNAP! asks which version of Dbase
you are using. You should answer "4" if this is a dBASE IV or
FoxPro system, or "3" if this is dBASE III or a dBASE III
"compatible" -- specifically Clipper, FoxBASE+, or
QuickSilver. Answer "2" for dBASE II or FoxBASE (original,
dBASE II variety).
SNAP! needs this information since different versions of Dbase
use different internal format for database and index files, as
well as different key words. SNAP! reads Clipper index files,
and handles Clipper source code and databases without
difficulty. If a specified dBASE III index file is not found,
SNAP! automatically searches for the corresponding Clipper
index file (with an NTX extension). SNAP! will also
automatically detect FoxBASE index files (IDX extension) and
document them properly.
Further, if you say that your system is a dBASE IV-type
system, SNAP! assumes that report form files are in dBASE IV
format. If they are not, the system can hang when SNAP!
bravely tries to read data that isn't there.
Ignoring Drive Designations
Sometimes you may want SNAP! to disregard explicit drive and
path designations when searching for data files. A choice on
the Other Options screen instructs SNAP! to drop any drive or
path designations before attempting to find a file. As an
example, you may have written a backup routine to copy a
database to B:BACKUP.DBF. If you would like SNAP! not to try
to find that file on the B: drive, choose the option to ignore
drive designations. This option has no effect on SNAP!'s
search for program files.
Printing SNAP! Documentation
SNAP! often produces a lot of documentation--perhaps more than
you will care to print. It is not uncommon for SNAP! to
produce several hundred pages of documentation for a Dbase
11
system of modest size. It could take days to print it all out
on anything but a laser printer.
I practically never print the documentation, but review it on
the screen instead. However, if you decide to print the SNAP!
documentation files, you have several options. First, you can
simply copy them to the printer like this:
COPY *.DOC PRN:
A second option is to add the documentation files to the
REPRINT.DOC file (you have to add them with an editor--SNAP!
doesn't do it automatically) and use the "immediate print"
capabilities of SNAP! (Press "F9--Print Now" from the Print
Options Screen) to print them.
Alternatively, you can use a program such as the LP program in
Norton Utilities to print the files. LP (it may be called
LINEPRNT on your system) prints the files with nice headings
and page numbers.
If you have a laser printer, I recommend that you take a look
at a Shareware program from Korenthal Associates called
4PRINT. It prints four pages of text on each physical piece
of paper and can greatly reduce the volume of printed SNAP!
documentation.
I have gotten permission from Korenthal Associates to
distribute 4PRINT on the SNAP! distribution disk. If you have
a laser printer, I encourage you to try 4PRINT. If you use it
and like it, please register it directly to Korenthal
Associates at 230 West 13th Street, New York, New York 10011.
Telephone: (212) 242-1790. It is also available on many
bulletin board systems. The registration fee for the full
package with printed documentation is about $40. Highly
recommended. When you register, please jot a note on the
form or tell them on the phone that you heard about it through
SNAP!.
You can also run SNAP!, create documentation and formatted
source code files, then later restart SNAP! and print the
source code. Whenever you choose to create a list of files
used in the system (FILELIST.DOC), SNAP! also creates the
REPRINT.DOC file that can be used to reprint all SNAP! source
code and action diagram files. Using the "F9--Print Now"
function on the print options screen, you can tell SNAP! to
print everything listed in REPRINT.DOC. Should you decide to
print any files in addition to source code and action
diagrams, you can add their names to REPRINT.DOC.
In addition to REPRINT.DOC, which holds the names of source
code files, SNAP! creates DOCLIST.DOC, which holds the names
of documentation files. Should you wish to, you can use the
12
"F9--Print Now" option to print SNAP! documentation files.
Even so, I recommend 4PRINT instead (see above).
Using a Mouse
SNAP! now supports mousing. You can use the mouse to position
the cursor in data entry fields, select function keys and
navigate the help system. To select one of the function keys
with the mouse, point at the function key definition on the
bottom of the screen.
In general, pressing the left button is like pressing the
enter key and pressing the right button is like pressing
escape. For example, pressing the right button from a data
entry screen calls the main menu, just as if you had pressed
escape.
There are a couple of wrinkles to using the mouse inside the
help system. Clicking on the little diamond in the upper left
corner takes you to the previous help screen if there was one.
Press the right mouse button to exit help. If there is more
than one screen of help, you can click on the arrow on the
right side to scroll the page.
13
SNAP! Commands
SNAP! supports several commands that you can insert in your
source code files. These commands will look like comments to
Dbase systems, but will have a special meaning for SNAP!. The
commands allow you to define macros, insert imaginary program
statements into your system, turn SNAP! features on and off
for particular parts of your system, and so forth.
Macros
SNAP! has a limited ability to do macro substitutions. To
define a macro, place the following line in your source code:
*# SNAPMACRO source target1 target2 . . .
Alternatively, or in conjunction with this method, you can
also define macro substitutions in a separate file. Specify
the /mfilename switch on the command line to tell SNAP! which
file the substitution strings are in. For example, the
following command will start SNAP! and read macro definitions
from the file FOO.MAC:
SNAP /mFOO.MAC
If you do not specify a filename with the /m switch, SNAP!
will try to find MACRO.SNP. You must use the full "*#
SNAPMACRO" command verb on each line of the file. Macro
substitutions defined in source code files take precedence
over those defined in a separate macro file.
The /O switch on the SNAP! command line disables all macro
processing, both from SNAPMACRO statements in source code and
in a named macro file.
Note that the SNAPMACRO statement begins with an asterisk and
a pound sign. SNAP! uses this sequence of characters to
designate a SNAP! command (see the /T command line switch for
information on how to change these characters). 'Source' must
be a single word, delimited by spaces or tabs. "Target" means
the rest of the line. Everything on the line--both source and
target--will be converted to upper case.
Note that the source string does not include the ampersand (&)
symbol for the macro (e.g., use SOURCE instead of &SOURCE).
The rest of the line (minus leading and trailing blanks) will
be used as a substitution string. The target can be a single
word or several words.
You cannot use && comments on a SNAPMACRO line since SNAP!
will think they are part of the target. If you want to
14
document the purpose of the SNAPMACRO statement, put a comment
on the line above it.
The SNAPMACRO statement can appear anywhere, as long as SNAP!
sees it before encountering the macro that you want to
replace. If the target will have the same value throughout the
system (e.g., FOO will always be replaced by BAR), it is a
good idea to put all of the macros in one place, perhaps at
the top of the TopFile or in a separate macro file.
If you would like SNAP! to use different macro values during
documentation, you may want to place the SNAPMACRO statement
immediately before the specific location of each macro
substitution. If you have multiple definitions for a single
macro, only the last one SNAP! sees will be effective. For
example, if the following series of statements are in your
program,
*# SNAPMACRO s_ddndx target1
*# SNAPMACRO s_ddndx target2
*# SNAPMACRO s_ddndx target3
only 'target3' will be effective and will be substituted for
each occurrence of &s_ddndx. See also the discussion of
SNAPCODE statements below for an alternative approach.
SNAP! will try to remove macros that look like drive or path
designations. For example, if the following statement is in
one of your programs:
USE &MPATH.DATABASE
SNAP! will detect the macro and remove it before trying to
find DATABASE.DBF. One consequence of this limit is that you
cannot use macros to refer to program files in different
directories. All source code program files (programs, format
files, memory files, etc.) must reside in the single program
directory you specify in the System screen. Databases and
indexes can be in either the program or data directories you
specify.
SNAP! will not substitute the macro in the code itself, but
will use the substitution value everywhere else. For example,
assume your program uses a database whose name is contained in
a macro variable named 'dataname'. Assume further that you
have included the following line in your code:
*# SNAPMACRO dataname ABC.DBF
If your code has this line in it:
USE &dataname
15
the source code will be unchanged after running SNAP!, but the
program headings and all other SNAP! reports will show this
program using the ABC.DBF database.
See also the section below "Fake Program Statements--SNAPCODE"
for other ideas on how to document macros.
Indirect References
In many circumstances, Clipper allows you to specify filenames
and other strings as indirect references. For example, the
following code is valid in Clipper Summer 87:
foo = 'FILENAME'
bar = '.TXT'
SET PRINTER TO (foo+bar)
This is equivalent to the statement:
SET PRINTER TO filename.txt
SNAP! partially supports indirect references. When SNAP! sees
one, it tries to apply macro substitution to the indirect
reference. Therefore, the following code will document
properly:
*# SNAPMACRO foo dbfname
USE (foo)
SNAP! will pick up the reference to the "dbfname" database.
However, more complicated indirect references will usually not
be picked up correctly. For example, SNAP! will not be able
to figure out what is going on in the following code:
dirname = 'CLIPPER'
USE ('C:\'+ALLTRIM(dirname)+'\filename')
When SNAP! encounters such an indirect reference, it does not
include it in the documentation. This limitation only applies
to Clipper systems, and only when you use indirect references.
You can use SNAPCODE (see below) to force this database to be
documented.
SNAPCODE--Fake Program Statements
Sometimes you may want to enter fake program source code
statements -- statements that SNAP! treats as real but which
do not actually interfere with your program when it executes.
A good example is a macro that calls one of a number of
programs, depending on the value it has at run time (e.g., DO
&program). The macro substitution discussed in the section
above provides a way for you to specify one value for
'program'. But suppose you wanted SNAP! to assume that
'program' had several values and to document each one in turn?
The *# SNAPCODE directive provides a way.
16
The *# SNAPCODE directive causes SNAP! to treat any text on
the line as if it were a program source code statement. In
the example above, you could enter the following lines where
the macro was called:
DO &program <---- in original program
*# SNAPCODE DO foo
*# SNAPCODE DO bar
*# SNAPCODE DO brlfq
SNAP! acts as if these were perfectly straightforward calls to
'foo', 'bar' and 'brlfq', and documents them accordingly.
dBASE and related systems ignore the statements.
Note that SNAP! does not know that these SNAPCODE statements
have anything to do with the DO statement above. SNAP! does
not associate 'foo' with 'program'. The next time SNAP! sees
'DO &program' it will not assume that 'program' has the value
'foo'. If you want SNAP! to associate values with macros, use
the SNAPMACRO directive.
As a side benefit, SNAPCODE statements help document your code
by specifying the permissible values that particular macros
can take.
Program Narratives
An important part of a well-documented system is a narrative
explanation of the purpose of each program module.
Unfortunately, SNAP! can't figure this out on its on.
However, it does allow you to describe your programs, and it
provides a way for your descriptions to be echoed to the
HEADINGS.DOC file. Any comments that start with "*)" will be
interpreted as program narratives and will be sent to
HEADINGS.DOC. Naturally, these comments will also be left
alone in the source code. Normally you will want to put these
narratives immediately below the SNAP! headings, but SNAP!
will recognize them wherever they are.
Other SNAP! Directives
Other SNAP! commands, or directives, allow you to turn cross-
referencing and program formatting on or off for particular
programs. For example, you may have "boilerplate" code that
you have thoroughly debugged and formatted which you insert
into many other systems. It would be unnecessarily
time-consuming to reformat this code every time you ran SNAP!.
SNAP! provides other commands to temporarily suspend
cross-referencing and formatting-- XREF, FORMAT, INDENT,
CAPITAL, and EXPAND. Each of these commands accepts three
17
settings--ON, OFF and SUSPEND. The ON and OFF commands are
effective until SNAP! sees another directive, while SUSPEND is
in effect only until the end of the current program or
procedure. For example, if you insert this line in your code:
*# SNAP XREF OFF
no tokens will be cross-referenced until this line is
encountered:
*# SNAP XREF ON
On the other hand,
*# SNAP XREF SUSPEND
suspends cross-referencing only for the current file. It
starts up again when the next program or procedure is
documented.
I suspend cross-referencing for commonly-used subroutines in
my code. For example, since Clipper does not have a BROWSE
command, I often include a public-domain BROWSE program in my
systems. This is a standalone module that really has nothing
to do with the rest of my system, and I don't want its
variables cluttering up my cross-reference report. So, I say:
*# SNAP XREF SUSPEND
at the top of the file and SNAP! leaves it alone.
SNAP FORMAT works in the same way. If format is off, no
indenting or capitalization will be done. When SNAP! sees a
SNAP FORMAT statement, it affects the internal codes that
determine whether indenting, capitalization and key word
expansion (or contraction) take place. The three commands
(INDENT, CAPITAL and EXPAND) turn specific features on or off.
Thus, the following sequence suspends indenting and
capitalization, but enables key word expansion:
*# SNAP FORMAT SUSPEND
*# SNAP CAPITAL ON
Thus, FORMAT is a shorthand way of referring to CAPITAL,
INDENT and EXPAND all at once.
If *# is an inconvenient sequence for you (e.g, it may cause
confusion with the British pound sign), you can change it with
the /T switch on the command line. For example, if you invoke
SNAP! with the switch "/T*$", SNAP! will use *$ to designate
SNAPMACRO, SNAPCODE and other SNAP! directives. You must
start this sequence with an asterisk (so that dBASE knows it
is a comment) and it cannot be more than three characters
long.
18
Source Code Formatting Options
File Headings
One of the most useful SNAP! features is a heading written to
each file in the system. Each heading indicates:
Program name
System name
Copyright notice
Author
Procedures defined within this file
Which programs this program calls
Which programs call this program
Databases, index files, report forms, format files, label
forms and memory files used by this program
Date and time documented.
A sample heading is included in the Appendix. The sample
heading indicates that TODOINP.PRG is called by TODOMENU,
calls TIME and TESTDATE, uses a file whose name is contained
in S_TDFILE with index TODO (macro substitution was not used
for this example), and also uses the TODOINP format file. The
heading also indicates the system name, author, copyright and
date documented. You may want to add more information to the
header, such as a brief narrative description of the program's
purpose.
If you choose to write headings on your source code files (or
if you choose any other option that modifies the source code
file), it is a good idea to send the output files to a
different directory than the input files so that your original
source code remains unchanged.
If you choose to send output files to the input directory,
your original source code file will be renamed with a .BAK
extension. If you use extensions to distinguish between
program files, some of your original source code files could
be destroyed. For example, if your system uses the following
program file names:
SYSTEM.INP
SYSTEM.EDT
SYSTEM.RPT
SYSTEM.DEL
and so on, the output files containing the headings will
retain these names. Each of the input files, however, will
have been renamed to a file called SYSTEM.BAK, and only the
last one will still exist when SNAP! completes. Therefore,
19
you should always send output files to a separate subdirectory
if you use this naming convention.
As always, you should make regular backups, and you should be
especially careful to make a full backup of all your files
before running SNAP!.
By default, SNAP! leaves the date and time of last update
unchanged for each of your files. You can instruct SNAP! to
update the date and time last changed on the source code
format screen. The headings written to each program file show
the date and time SNAP! was run.
Indentation
SNAP! can also help format your source code to make it easier
to read. SNAP! can recognize dBASE control structures and
indent the program statements underneath them. By default,
indentation is three spaces. (The author, who has long argued
the superior virtue of tab characters for indenting code, has
caved in to overwhelming user pressure on this point. He
still uses tabs in his code and believes you should too. But
the default is now three spaces.) In addition, should you
choose to use SNAP!'s source code printing routines, you can
select the number of spaces to be inserted for each tab as the
code prints.
However, if you would like to use spaces rather than tab
characters for indenting, you can select this option from the
Format options screen. For example, you can instruct SNAP! to
use three spaces for each indentation level. This option has
no effect if you do not choose to indent source code. It is
different from the option in the source code printing facility
that also allows you to expand tabs. If you choose to use
spaces to indent your source code files, the source code will
not contain tabs, so the source code printing tab-expansion
feature will have no effect.
If you choose to indent source code or create action diagrams,
SNAP! will also scan your code for mismatched control
structure terminators. For example, if your code has the
following sequence:
20
DO WHILE T statements
.
.
.
IF X = Y
.
.
ENDIF
ENDIF <---- incorrect
SNAP! will detect that the final statement should have been an
ENDDO instead of an ENDIF and will display an appropriate
error message. SNAP! will accept 'END' as a valid
abbreviation of ENDDO, ENDIF or ENDCASE.
SNAP! does not track control structures across program or
procedure boundaries. Normally, this is not a problem since
you cannot start a DO WHILE loop in one program and finish it
in another. BREAK statements, however, can exit from a
BEGIN/END SEQUENCE control structure that is defined in
another program. If SNAP! encounters a BREAK statement but
cannot find the BEGIN/END SEQUENCE structure, it reports an
error. Just ignore it if you know that the BREAK is valid.
Most people indent CASE statements in the following way, as
God intended:
DO CASE
CASE foo = bar
CASE xyzzy = plugh
ENDCASE
Certain stubborn users, however, who persist in the error of
their ways in spite of my best efforts to point out their
character flaws, insist on indenting CASE statements like
this:
DO CASE
CASE foo = bar
CASE xyzzy = plugh
ENDCASE
If you invoke SNAP! with the -A command line switch, you too
can use this wretched technique.
Capitalization
SNAP! will also capitalize dBASE key words found in your
source code. Key words are stored in a file called
DBxWORDS.SNP where x is a 2, 3 or 4 depending on the version
of dBASE you are using (you can also specify another file).
21
SNAP! does not attempt to parse code statements to determine
how a word is used, so if you use key words as variable or
field names, they will also be capitalized. Should you wish
not to capitalize a particular key word, you can either delete
it from the DBxWORDS.SNP file, or "comment it out" by putting
an asterisk before it in the file (e.g., RELEASE becomes
*RELEASE).
The preceding paragraph assumes you prefer "standard"
capitalization--key words are capitalized, functions have an
initial capital letter, and everything else is in lower case.
If not, you can change it on the Format screen. You can
select upper case, lower case, initial caps, or none (leave it
alone) for both tokens and for key words. Thus, if you were
so inclined, you could capitalize tokens (variables, etc.) and
lowercase key words.
Key Word Expansion and Compression
SNAP! will allow you to expand abbreviated key words to their
full length, or to abbreviate the key words to four
characters. Compilers don't care about any of this, but the
dBASE interpreter runs programs slightly, usually very
slightly, faster if the key words are abbreviated to their
first four characters. An option on the Format screen
controls how expansion or compression is done. The default is
no expansion or compression--SNAP! leaves your code alone.
However, you can select expansion, or compression to any
number of characters between 4 and 9.
Please be careful with this option, especially if you are not
very careful about how you name variables. The only thing
SNAP! knows about key words are that they are in the key words
file. If one of your variables is a key word (or a valid
abbreviation of a key word), SNAP! will cheerfully expand or
contract it along with everything else. SNAP! cannot tell how
whether a particular word is being used as a command or as a
variable. Normally, this will not be a big problem--if you
named a variable "title" and compressed key words, it will now
be called "titl". Problems could arise, however, if two
variables are valid abbreviations of the same key word (e.g.,
"other" and "otherw", both of which are valid abbreviations of
OTHERWISE). If you compress key words and have such variable
names, both variables will be compressed to OTHE, and there is
no way to separate them again. Also, if you are using a
dialect of Dbase that supports user-defined functions (UDFs),
and if one of the UDFs has the same name as a key word (Tom
Rettig's BLANK() function, for example), the UDF name will be
compressed (assuming the UDF name was in the key words file).
If you compress keywords in this case, nothing desirable will
happen.
22
Because of the irrevocable changes that this option can make,
SNAP! will not allow you to exercise it if the source and
output directories are the same. In other words, SNAP! will
refuse to overwrite your original source code files if you
select this option. Big brother is looking out for you.
If you use the compression option, please run the compressed
code and ensure that it works before you delete the backups
that SNAP! made.
Key words that are identified in the key words file as
functions (they have () after their name--see below) are never
affected by key word compression or expansion.
Suppressing Blank Lines and Comments
You can suppress blank lines and/or comments from the output
files by selecting the appropriate options on the Format
screen. I do not recommend this, but it does make interpreted
Dbase applications run slightly faster. Please be doubly sure
to make backups before doing this. SNAP!'s default options
are to leave both blank lines and comments in the output file,
so you have to take special action yourself before they will
be dropped.
As with key word expansion and compression, you cannot select
this option if the source and output subdirectories are the
same.
If you know how to design an effective counterpart to this
feature--how to put the comments back in--please contact me
about a potentially lucrative commercial venture.
Key Words File
Capitalization, cross-referencing and key word expansion and
compression are controlled by the words in the key words file.
The key word file should contain one key word per line.
Capitalization and order do not matter, except that if two
identical key words have different flags (see below), the last
one takes precedence.
By inserting the correct characters in the key word file, you
can cause certain key words or variables to be handled
differently than normal. The following characters have a
special meaning in the key word file when inserted immediately
before a word:
23
* Comments out the word. SNAP! acts as if it were not in
the key word file at all.
! Capitalize, but do no cross-reference even when the
option to cross-reference key words is in effect. You
may want to use this character for often-used but
uninteresting key words such as TO or, perhaps, SAY.
@ Capitalize and always cross-reference this word, even
when the option to cross-reference key words is not in
effect. You might want to use this for especially
important key words such REPLACE, SAVE, or QUIT.
% Neither capitalize nor cross-reference, regardless of
whether the options to capitalize or cross-reference key
words are in effect. You may want to use this character
for variables that you use frequently, but that you are
not interested in cross-referencing--perhaps "i",
"choice", "action", or "lineno". This will keep them
from cluttering up the cross-reference report. Such
words are not affected by key word expansion or
contraction.
() If the *last* two characters in a key word are (), the
key word will ordinarily have an initial capital letter
in the formatted output. The DB3WORDS.SNP file that
comes with SNAP! uses this notation to designate the Tom
Rettig key words (Tom Rettig is the author of a popular
set of functions for dBASE III and Clipper) and the
keywords in the PROCLIP3 library. Functions are never
affected by key word expansion or contraction.
The following examples illustrate how to use these special
characters:
*note
!SAY
@REPLACE
%CHOICE
SOME_FUNCTION()
There are two ways to tell SNAP! about key words. First, the
Format screen allows you to specify the main key words file,
which will usually be DB4WORDS.SNP for FoxPro or dBASE IV
systems, DB3WORDS.SNP for Clipper, dBASE III and FoxBASE+, and
DB2WORDS.SNP for any wretches still using dBASE II. In
addition, SNAP! will look for a file called PERSONAL.KEY in
the SNAP! subdirectory (the subdirectory where you put SNAP!--
it doesn't actually have to be named "SNAP!"). Anything found
in PERSONAL.KEY will be treated just as if it were in, say,
DB4WORDS.SNP. Therefore, you can customize your key words
24
list without messing up the factory-installed DB4WORDS.SNP
file.
SNAP! is distributed with key words files for a variety of
third-party function libraries. Naturally, different
programmers will use different libraries. If you use one of
the supported libraries, just include its key words into the
main SNAP! key words file (e.g., DB4WORDS.SNP) or into your
PERSONAL.KEY file. The best way to add a library's key words
is to put "*# INCLUDE" statements like this in your
PERSONAL.KEY file or into DB4WORDS.SNP:
*# INCLUDE rettig.key
*# INCLUDE proclip.key
SNAP! will then recognize all the key words in RETTIG.KEY.
These "*# INCLUDE statements" can be nested, but they have to
be in either the main key words file or in PERSONAL.KEY. A
"*# INCLUDE" statement in a source code file is ignored. In
addition to using "*# INCLUDE" statements, you can use a word
processor or program editor to move the words into
PERSONAL.KEY or DB4WORDS.SNP.
"Support" for third-party libraries is really just a list of
key words. You can easily add key words from any other
library that I didn't include--SNAP! itself doesn't have to be
modified.
SNAP! provides enough space for a maximum of 1,500 key words.
This is far more than is required for all dialects of Dbase
put together, but is not enough for all of the third-party
libraries also. Therefore, you should just update the main
key words file for the libraries you actually use. Any key
words past the limit will be ignored.
SNAP! does not try to detect duplicate key words. They don't
cause any harm, but they all count against the limit. If you
have duplicate key words with different control characters
(see above), the control character set that will be used by
SNAP! is deterministic but unpredictable.
25
Reports and Outputs
SNAP! can produce any combination of several reports. Each
report is optional and can be selected or suppressed on the
Options Screen. However, some reports (e.g. Data dictionary,
Index summary) require you to search the tree rather than
document a single program.
Normally, SNAP! tells you that it is producing a particular
report, but does not display the report on the screen.
However, each report other than a file heading, may be
displayed on the screen as it is echoed to a file. You can
enable screen echoing by invoking SNAP! with the /S command
line parameter. I like to see the reports being generated but
some people prefer to silence the screen to improve SNAP!'s
speed. Note that the /S switch only affects the screen
display of reports and has no effect on the status screens
that are displayed as SNAP! scans source code files.
The program contains default filenames (e.g., XREF.DOC for the
cross-reference report), but you can change them if you wish.
Controlling the Printer
SNAP! allows you to specify a number of parameters for
controlling your printer. These parameters include margins,
setup strings, and so forth. In addition to entering them
directly, you can also press F2 and select some standard
printer configurations from a scrollable list. These printer
definitions are stored in the SNAPPRT.SNP file, an ASCII file
which you can edit yourself to add more printer definitions.
SNAP! supports up to 10 printer definitions.
System Summary
This report shows the following information:
System name
Author
Current date and time
Lines of code
Number of programs, procedures, procedure files, indexes,
and so forth
Names of databases, indexes, report forms, label forms and
memory files
The system summary would ordinarily be the first page in the
documentation. It, together with the tree diagram, provides a
basic overview of the entire system. See Appendix A for an
example.
26
Tree Structure Diagram
If you choose the default option of documenting all programs
in the tree, SNAP! will produce a chart showing which programs
call which other programs and which programs use which
databases. The tree diagram, like other SNAP! reports,
appears on the screen and is echoed to a file (default name of
TREE.DOC).
Any procedures or databases in the tree will be designated
like this:
Gee (procedure in procedure.file)
Whiz (database ALIAS baz)
SNAP! by default includes programs, procedures, functions,
format files and databases in the tree. The Tree Screen
includes options that allow you to put indexes, report forms,
label forms and memory files in the tree also, or to suppress
any of the default file types except program files.
Note that the databases (and other non-program files) are
shown underneath the programs that actually call them. If a
database is opened in one program and remains open in another
program, SNAP! will show the database as called only by the
first program file.
SNAP! has some code to detect certain types of recursion and
prevent the tree from marching off the right side of the page
and eventually off the end of the world. SNAP! catches
programs that call themselves and programs that call another
program that calls the original program again. If the
recursion is more subtle than that, SNAP! will eventually give
up when recursion reaches 25 levels. You will have become
bored watching the display by that point.
SNAP! detects calls to other programs, procedures and
functions when they are in one of the following formats:
DO something
SET KEY 300 TO something
ON KEY 300 DO something
ON KEY=300 DO something
ON KEY DO something
ON KEY LABEL keylabel DO something
ON ESCAPE [or ERROR] DO something
ON READERROR DO something
ON SELECTION PAD ... DO something
ON SELECTION POPUP ... DO something
ON PAGE x AT LINE y DO something
foo = something() <---SNAP! detects other UDF calls also
CHAIN something
SWITCH something
SET FORMAT TO something
27
Further, SNAP! detects calls to user defined functions in
certain Clipper functions--MEMOEDIT, DBEDIT and ACHOICE.
SNAP! searches through procedure files to generate a complete
list of procedures and functions. It identifies procedure
files in the following ways:
EXTERNAL procfile
SET PROCEDURE TO procfile
SET UDF TO procfile
Also, SNAP! will detect any procedures that are tacked on to
the bottom of a PRG file, a coding style that Clipper allows.
There are other "things" that sometimes act like programs.
For example, dBASE IV creates an FRG file whenever you use its
report writer. In reality, this file is a procedure file that
contains code to produce the report. SNAP! detects that an
FRG file exists and shows it begin called from the program
that initiates the report--the one that contains the REPORT
FORM ... TO ... statement. Similarly, label LBG files are
also detected and documented.
The tree report is illustrated in the Appendix.
File List
SNAP! can write a simple list of all files used in the system,
including programs, databases, index files, and so on. This
report can be useful for identifying which files in a
directory are associated with an application. The file list
can also be fed into the source code printing routines at a
later point, so that the program files can be printed without
going through a time-consuming complete documentation run
again.
Data Dictionary
The data dictionary report contains two parts: 1) the database
structure for each database in the system and a list of
programs which use it; and 2) a listing of each data field in
the system and the databases that contain it.
SNAP! tries to figure out which indexes, report forms and
label forms are associated with each database. It tracks the
following statements:
USE dbfname
SELECT A (or B, C, etc. up through J)
SELECT aliasname
CLOSE DATABASES
CLOSE ALL
USE
28
SNAP! knows how to account for macros in each of these
constructions, assuming you have defined the macro. For
example, USE &temp will be interpreted to mean USE abcfile if
you have previously defined &temp to mean abcfile (see section
on SNAPMACRO statements for more details).
SNAP! is reasonably good, but certainly not perfect, at
figuring out which database is active at a particular spot in
the code. There are, however, some limitations you should be
aware of. First, SNAP! does not track databases or areas
across program files or procedures. Whenever SNAP! begins
documenting a file, it assumes that no databases are in use
and that area A is active. Also, SNAP! does not try to
interpret conditional structures. For example, consider the
following code:
IF .T.
USE foo
ELSE
USE bar
ENDIF
SNAP! looks at this code one line at a time. The last USE
statement it sees is 'USE bar'. That statement will never
actually be executed (because of the IF test), but SNAP!
doesn't know that. You may need to use SNAPCODE statements to
help SNAP! figure out what is happening in cases such as this
one.
SNAP! identifies databases in these ways:
1) USE statements, but only those followed by a database
name;
2) COPY TO statements, including COPY TO ... SDF. If the
command copies to an SDF file that does not have an
explicit extension, SNAP! supplies .TXT. Otherwise SNAP!
assumes databases to have .DBF extensions.
3) DELETE FILE xxx.DBF
4) CREATE foo FROM bar (SNAP! picks up both foo and bar)
5) CREATE foo
6) COPY FILE foo.dbf TO bar.dbf
7) COPY STRUCTURE [EXTENDED] TO foo
8) SORT ON keyname TO foo
A statement that tests for the existence of a database (e.g.
IF FILE("xyz")) will not by itself be identified as a database
reference. Currently, SNAP! imposes an overall limit of 1,024
fields in the entire system. If you exceed that number, SNAP!
complains and does not include the excess fields in the data
dictionary.
A sample data dictionary report is included in appendix A.
29
Index File Summary
The index file summary lists each index file referenced in the
system and attempts to show the fields it is indexed on and
the files that use it. It also shows multiple index files and
their tags in a separate section of the report.
SNAP! first checks for an index file with the default
extension you specified on the "Other Options" screen. If it
cannot find a file with that extension, it tries to find one
with an extension of NDX (the usual extension of dBASE II,
dBASE III index files). If it cannot find this file, it tries
to find the same file name with an NTX extension (the usual
extension of Clipper index files). Failing that, it tries
FoxBASE+/FoxPro IDX extensions. If SNAP! cannot find one of
those either, it gives up and reports that the NDX file could
not be found. If, however, it could find the Clipper or
FoxBASE+/FoxPro file, it documents it appropriately.
SNAP! also shows the database associated with each index, if
it could figure it out. The data dictionary section of this
documentation discusses the assumptions that SNAP! makes about
which database is active.
SNAP! identifies indexes in five ways:
1) INDEX ON xyz TO indexfile
2) USE xyz INDEX indexfile1,indexfile2,indexfile3 ...
3) SET INDEX TO indexfile1,indexfile2,indexfile3 ...
4) DELETE FILE xyz.NDX
5) COPY FILE foo.ndx TO bar.ndx
In cases 2 and 3, each index file will be separately
identified and documented.
A statement that tests for the existence of an index (e.g. IF
FILE("xyz.NDX")) will not by itself be identified as an index
reference.
SNAP! identifies multiple index files (MDX files) in the
following ways:
1) INDEX ON bar TAG foo OF xyz
2) USE xyz (when XYZ.MDX exists)
3) SET INDEX TO xyz
4) COPY TAG foo OF xyz TO ndxname
A sample index file summary in shown in the Appendix.
30
Format File Summary
SNAP! also produces a report showing each format file used in
the system and the programs that call it. A sample report is
in the Appendix.
SNAP! identifies format files in two ways:
1) SET FORMAT TO xyz
2) DELETE FILE xyz.FMT
In case 1, if this is a dBASE II system, SET FORMAT TO SCREEN
and SET FORMAT TO PRINT are not flagged as references to
format files.
A statement that tests for the existence of an format (e.g. IF
FILE("xyz.FMT")) will not by itself be identified as an format
reference.
Report Form Summary
SNAP! also produces a report showing each report form used in
the system, the report parameters, and the programs that call
it. For dBASE III, FoxBASE+ and Clipper systems, SNAP! shows a
mock- up of each report and the expressions that go into each
column. It also indicates which database is associated with
the report form.
Documentation for dBASE IV and FoxPro report formats is
simpler and does not include a mock-up of the report.
Documentation for both dBASE IV and FoxPro shows the fields or
expressions that comprise the detail records. Since both
systems contain very sophisticated and elaborate report
generators, it is not practical to summarize how the report
looks, so SNAP! focuses on its contents. You may wish to take
a screen print of the report generator as additional
documentation. Also, apart from the documentation that SNAP!
automatically produces, you may wish to retain a sample report
printout. Such a sample is probably a better indication of
what the report does than the SNAP! documentation.
A sample dBASE III report is in the Appendix.
SNAP! identifies report forms in two ways:
1) REPORT FORM xyz ...
2) DELETE FILE xyz.FRM
A statement that tests for the existence of an form (e.g. IF
FILE("xyz.FRM")) will not by itself be identified as an report
form reference.
31
Label Form Summary
The label form summary shows the parameters of each label form
in the system. It also indicates which database is associated
with each label form. A sample report is in the Appendix.
Procedure File Summary
SNAP! allows you to prepare a summary of files that contain
procedures (see example in appendix A). This summary shows
the procedures in each procedure file and the programs and
procedures that each one calls and is called by. The report
shows each procedure and function in the TopFile system.
SNAP! also reports the parameters expected by any procedures
or functions that accept parameters. Note that this report
covers both procedure files and ordinary program files that
also contain procedures (as Clipper allows).
Other Summary Reports
SNAP! also produces summary reports for the following
additional file types:
1) Memory files
2) Binary (LOAD/CALL) files
3) Other files
Other files are generally text files that are specified in the
following ways:
1) SET ALTERNATE TO xyz
2) SET PRINTER TO xyz
3) COPY MEMO to xyz
4) APPEND MEMO FROM xyz
5) COPY FILE xyz TO abc <-- when SNAP! doesn't recognize
the file extension
6) TYPE xyz
The other files summary report lists these files and shows
which programs or procedures made a reference to the file. I
don't guarantee that the report will pick up every possible
"other" file, but it seems to catch all of them in the sample
code I use to test it.
Variable Cross-Reference Report
Another useful report available through SNAP! is a variable
cross-reference listing, showing line numbers for each program
that references a particular variable. 'Variable' in this
32
context includes field names, file names and anything else
that isn't a key word, numeric constant, punctuation mark or
quoted string.
If you elect to display the variable cross-reference report
(by responding 'Y' to the question on the options menu), you
can view the Cross-reference Options Screen. The
Cross-reference Options Screen allows you to select the type
of "things" that will included on the cross-reference report.
You will have the option to include only PUBLIC variables
(this option has no meaning if this is a dBASE II system).
You also get the following choices:
Include other variables and tokens
Include key words
Include numeric constants
Your responses to these prompts (and your use of special
characters in the key words file--see below) determine which
words will appear on the cross-reference report.
The cross-reference report adds certain codes to the end of a
line number reference when the reference is particularly
interesting. SNAP! looks for the following statements to tell
if a variable or field name (assume its name is 'abc') is
interesting:
Reference Type Report Flag
abc = 4 *
STORE 4 TO abc *
WAIT to abc *
@ 1,1 GET abc PICTURE "blah, blah" G
ACCEPT "something" TO abc G
INPUT abc G
REPLACE abc WITH something R
RELEASE abc x
PUBLIC abc P
PRIVATE abc V
&abc &
DECLARE abc[100] A
DIMENSION abc(100,200) A
USE abc [INDEX ...] [ALIAS ...] U
DO foo WITH @abc @
As the following sample excerpt from the cross reference
report illustrates, you can tell at a glance what is happening
to the variables you are using:
ABC
TODO.PRG 30P 41 42 43G 44 45* 46G 47G
TDINPUT.PRG 123V 234* 235 237
33
SETFILT.PRG 16 24 28 32
TDEDIT.PRG 107* 133 134 135 136 138x
This report shows that variable 'abc' was used in four
programs (TODO, TDINPUT, SETFILT and TDEDIT). Within TODO, it
was declared a PUBLIC variable on line 30; referenced but not
changed on lines 41, 42 and 44; used in a GET statement on
lines 43, 46 and 47; modified in line 45; and released on line
72. TDINPUT declared it to be PRIVATE (line 123), assigned it
a value in line 234, then referred to it in lines 235 and 237.
A legend to explain all these flags is printed at the top of
each cross-reference report, so you do not need to remember
what they all mean.
SNAP! will not flag a 'RELEASE ALL' statement as a reference,
nor will it figure out that a 'RESTORE FROM xyz.mem' may
overwrite other variables. Neither of these statements will
generate a cross-reference listing for any variables (though
xyz.mem will be referenced). Of course, you can have SNAP!
cross-reference the RELEASE and RESTORE statements themselves.
By default, references to a database field prefaced by the
alias (e.g., foo->bar) will be shown as one token in the cross
reference file. If you do not like this convention, the /C
command line option turns it off, so that foo and bar will be
referenced separately.
At the bottom of the report, SNAP! produces a list of public
variables, a list of macros and a list of arrays. The macro
list is subdivided into macros that you defined to SNAP! and
those you didn't. If you defined a macro, its definition is
also shown.
The cross-reference report interacts closely with the key word
file. Specifically, the key word file is how SNAP! can tell
what is a key word and what is not. Additionally, by
inserting the correct characters in the key word file, you can
cause certain key words or variables to be handled differently
than usual. The following characters have a special meaning
in the key word file when inserted immediately before a word:
* Comments out the word. SNAP! acts as if it were not in
the key word file at all.
! Capitalize, but do no cross-reference even when the
option to cross-reference key words is in effect. You
may want to use this character for often-used but
uninteresting key words such as TO or, perhaps, SAY.
@ Capitalize and always cross-reference this word, even
when the option to cross-reference key words is not in
34
effect. You might want to use this for especially
important key words such REPLACE, SAVE, or QUIT.
% Neither capitalize nor cross-reference, regardless of
whether the options to capitalize or cross-reference key
words are in effect. You may want to use this character
to designate variables that you use frequently, but that
you are not interested in cross-referencing--perhaps "i",
"choice", "action", or "lineno".
() If the *last* two characters in a key word are (), the
key word will ordinarily have an initial capital letter
in the formatted output. The DB3WORDS.SNP file that
comes with SNAP! uses this notation to designate the Tom
Rettig key words (Tom Rettig is the author of a popular
set of functions for dBASE III and Clipper).
The following examples illustrate how to use these special
characters:
*note -- This word will be ignored.
!SAY -- Capitalize, but do not cross-reference, SAY.
@REPLACE -- Include REPLACE in the cross-reference
report.
%CHOICE -- Do not capitalize or cross-reference this
word.
Alltrim() -- This word is a function. The first letter
will be capitalized.
If this is a dBASE III or dBASE IV system, SNAP! allows you to
restrict the cross-referencing to PUBLIC variables. If you
select this option, SNAP! only puts public variables on the
report. However, SNAP! does not look for PRIVATE statements
that redefine the variable, so if a variable is declared
PUBLIC anywhere in the system, SNAP! documents all subsequent
occurrences of it. Note that SNAP! does not "backtrack" to
see if the variable was referenced before it was defined as
PUBLIC.
I have done my best to identify key words used in dBASE,
FoxBASE and Clipper, but I may have missed some. Fortunately,
the DBxWORDS.SNP file is a standard ASCII file that you can
edit with most any word processor. So, if I have omitted one
of your favorite key words, it is a simple matter to add it to
the file. Function names from other third-party libraries are
also included, but you may also want to add function names
from other development tools.
A sample cross-reference report is included in the Appendix.
35
LNK and MAKE files
These options will be useful only to developers of
Clipper-compiled applications. If you are using interpretive
dBASE III, dBASE IV or FoxPro you can ignore this section.
Link Files. SNAP! can produce a link file for PLINK86 (which
comes with Clipper), TLINK (part of the Borland Turbo C
package), and the Microsoft LINK utility. If you are a
serious Clipper programmer, the TLINK linker justifies the
cost of the Turbo C package (less than $100)--it is that fast.
I have seen some informal benchmarks that show it linking
applications as much as eight times faster than PLINK86. Note
that TLINK versions 2.0 and higher do not work correctly with
Clipper.
PLINK86 will accept "commands" from a LNK file. This file
typically contains a series of commands for the linker,
telling the linker such things as which libraries to search
and in what order. SNAP! will produce a LNK file if you
select the appropriate option. This LNK file will contain a
list of all the files in your system.
If you have a file named LINK.SNP in your source directory,
SNAP! will put it at the top of the LNK file. For example,
you might put a list of libraries in this file. You can also
use a name other than 'LINK.SNP' by specifying /Lfilename on
the command line.
Make Files. SNAP! can produce the files for the Clipper MAKE
utility (Summer 87 version only) and for the Shareware NDMAKE
program.
MAKE is a standard UNIX (tm) utility, versions of which are
now also available for MS-DOS. MAKE allows you to define
which files "depend" on other files and only compile files
that have changed. For example, in a Clipper application using
MAKE, you would typically have one OBJ file for each PRG file.
Each OBJ file "depends" on the corresponding PRG file since
the OBJ file needs to be remade when the PRG file changes. In
other words, when a change is made to a program file, it needs
to be recompiled to create a new object file. Similarly, the
EXE file "depends" on all of the object files that are linked
together to create it.
MAKE allows you to specify these dependencies and perform the
fewest recompiles to completely update your system for all
program changes. It can save an enormous amount of time on the
edit-compile-link-run cycle for a large system development.
NDMAKE use three files--the MAKE.EXE file itself, a MAKE.INI
file that specifies certain defaults, and a file named
36
MAKEFILE that contains the dependencies for your system.
SNAP! can create the MAKEFILE. It is up to you to deal with
MAKE.INI. In particular, you will need to add a default rule
to your MAKE.INI file to tell MAKE how to compile a PRG file
into an OBJ file. Its syntax is:
# To produce a `.obj' file from a `.prg' file using Clipper.
.prg.obj:; clipper $< -m
This definition should work with most versions of MAKE. If
you use a different MAKE utility, you may need to use slightly
different syntax here. Check your documentation to be sure.
The SNAP! MAKE option works hand-in-hand with the LNK option.
If you ask SNAP! to create a LNK file, SNAP! will use the same
file name when it create MAKEFILE.
The net effect of all of this is that you can issue the
command:
MAKE filename (where filename is the name of your TopFile)
and MAKE will figure out what needs to be recompiled and
linked to create your system.
Sample LNK and MAKEFILE listings are included in appendix A.
Batch Files
SNAP! also produces DOS batch files to do useful things. One
file, named UPDATE.BAT, will copy all program files from the
SNAP! output directory to the original source directory. You
could use it to copy the new (documented) versions of your
source files over the original (undocumented) source files.
The syntax for UPDATE is:
UPDATE d:
where d: is a drive or directory name. If it is omitted, the
original source directory is assumed. Be careful with this
file since it overwrites the original source code files. You
should backup your original files and review the new output
files before executing UPDATE. No kidding. This is
important.
BACKPRG backs up the programs, format files and report forms
in your system. Its syntax is:
BACKPRG d:
37
d: is a drive or directory name and is required. If you do
not specify a target drive or directory, the batch file will
complain and stop.
BACKDBF backs up the databases, index files and memory files
in your system. Its syntax is:
BACKDBF d:
d: is a drive or directory name and is required. If you do
not specify a target drive or directory, the batch file will
complain and stop.
Macros are suppressed from this file.
Also, SNAP! creates the PRINTDOC.BAT file to send all
documentation files (not including source code or action
diagrams) to the printer. PRINTDOC calls the DOS PRINT utility
for background printing. Thus, PRINT must be available
somewhere on the path.
Action Diagrams
An action diagram documents the structure of a program by
using graphical symbols to group related statements together.
By default, SNAP! uses the IBM extended ASCII characters in
the action diagrams it prepares.
38
A portion of a sample action diagram follows:
┌─IF s_clipper .AND. s0_filt = 7
│ ╔═DO WHILE .NOT. s0_userfilt
│ ║ SKIP
│ ║ ┌─IF EOF()
│ ║ │ GOTO TOP
│ ║ │ ╔═DO WHILE .NOT. &s0_userfilt
│ ║ │ ║ SKIP
│ ║ │ ║ ┌─IF EOF()
│ ║ │ ║ │ SET FILTER TO
│ ║ │ ║ │ s0_userfilt = "1=1"
│ ║ │ ║ │ GOTO TOP
│ ║ │ ^═══════LOOP
│ ║ │ ║ │ ┌─IF Dusty Day In The Lake
│ ║ │ ║ │ │ ? "Yell and Scream"
<═══════════════════RETURN
│ ║ │ ║ │ └─ENDIF
│ ║ │ ║ └─ENDIF
│ ║ │ ╚═ENDDO
│ ║ │ ╒═DO CASE
│ ║ │ ╞═CASE lastkey() = 4
│ ║ │ │ choice = "F"
│ ║ │ ╞═CASE lastkey() = 19
│ ║ │ │ choice ="B"
│ ║ │ ╘═ENDCASE
│ ║ └─ENDIF
│ ╚═ENDDO
│ ╓─FOR i = 1 TO 25
│ ║ DO sample1
│ ╙─NEXT
└─ENDIF
As this example shows, different extended ASCII characters are
used to differentiate different control structures. Loops (DO
WHILE, FOR, SCAN) use the double-line vertical bar, while
conditional statements (IF, DO CASE) use a single vertical
bar.
The structures are distinguished further by the horizontal
symbol used to connect the control structure key word with the
vertical bar.
Note also that these diagrams allow you to identify "unusual"
loop exits such as LOOP and RETURN very easily. I can often
identify subtle, difficult-to-locate bugs by studying the
action diagram for the program.
SNAP! will identify certain syntax errors (such as a LOOP
statement that is not within a DO WHILE loop) only if you
39
choose to prepare action diagrams. Certain error checking is
only performed within this module.
The Format screen allows you to choose whether to write action
diagrams or not. It also allows you to specify the extension
that action diagram files will have. Action diagrams always
have the same main file name (i.e, the first eight characters)
as the source code file from which it is drawn, but the
extension can be anything you specify except '.PRG'. You can
use the '?' character as a wildcard to match the corresponding
characters in the original file extension. Therefore, if you
choose an action file extension of'??T', and your original
source file was named FOO.BAR, the action diagram file will be
named FOO.BAT (the BA is drawn from the original filename, and
the T comes from the action diagram file mask).
Action diagram files are very much like program files and have
the same capitalization as the output program files do.
However, action diagram files are not directly executable or
compilable because of the additional line-drawing characters
they contain.
Some printers (most Epson models, for example) do not support
the IBM graphics characters very well. If you want to print
action diagrams, you may want to use other characters for the
connections. You can choose to prepare action diagrams using
only ASCII symbols by choosing the ASCII symbol option on the
source code and action diagram options screen.
You can also choose your own action diagram symbols on the
'SourceCode and Action Diagram Options' screen. The following
chart shows how to customize the symbols:
Default symbols: ─│┌└├═║╔╚^v═│╒╘╞─║╓╙<═
Position: 0000000001111111111222
1234567890123456789012
Position Symbol
-------- -----------------------------------------------------
1 Horizontal symbol used for IF/ELSE/ENDIF structures
2 Vertical symbol used for IF/ELSE/ENDIF structures
3 Corner for IF and BEGIN SEQUENCE (Clipper only)
4 Corner for ENDIF and END (Clipper only)
5 Join symbol for ELSE
6 Horizontal symbol used for DO WHILE/ENDDO structures
7 Vertical symbol used for DO WHILE/ENDDO structures
8 Corner for DO WHILE
9 Corner for ENDDO
10 Symbol for LOOP
11 Symbol for EXIT and BREAK (Clipper only)
12 Horizontal symbol used for DO CASE/OTHERWISE/ENDCASE
40
structures
13 Vertical symbol used for DO CASE/OTHERWISE/ENDCASE
structures
14 Corner for DO CASE
15 Corner for ENDCASE
16 Join symbol for CASE and OTHERWISE
17 Horizontal symbol used for FOR/NEXT structures
18 Vertical symbol used for FOR/NEXT structures
19 Corner for FOR
20 Corner for NEXT
21 Arrow symbol for RETURN/CANCEL/QUIT
22 Horizontal symbol used for RETURN/QUIT/LOOP/EXIT
You can replace any of these symbols with others of your
choosing. If you want to restore the default set, simply
select 'G' for graphics characters, move to another input
screen, then come back again (in simpler terms, select 'G',
press Ctrl-PgDn then Ctrl-PgUp). These symbols are reset when
the 'Source Code and Action Diagrams Options' screen is
presented. One consequence is that you must answer 'O' (for
Other Symbols) to be able to change the action diagram
symbols. If you answer 'G', then change the symbols, the
changes will not take effect. Like other input fields, any
user-defined symbols will be saved in the configuration file
so you do not have to enter them at each invocation of SNAP!
The SCAN/ENDSCAN control structure is documented with the same
symbols as the DO WHILE loop. The BEGIN SEQUENCE/BREAK/END
control structure is diagrammed with the same symbols as an
IF/ENDIF structure.
Source Code Printout
When you have completed your program, you will probably want a
listing of the source code to accompany the rest of your
documentation. SNAP! provides a facility for formatting and
printing dBASE source code files and/or action diagrams, and
gives you a great deal of control over source code format.
You can set the following parameters:
Line width
Page length
Left and right margins
Top and bottom margins
Spaces per tab
Include or suppress line numbers
Printer setup string
For example, you can set these values to leave plenty of room
on the left side of the page so that your code will fit in a
3-ring binder.
41
If a line of code exceeds the line width minus left and right
margins, SNAP! will wrap it on the printout without messing up
the page breaks. SNAP! also appropriately counts the wrapped
line as one source code line, so that your cross-reference
report still matches the printout.
Each page of the printout contains a header showing the
program name, system name, copyright notice, page number and
date/time printed. The programs are printed in alphabetical
order.
Line numbers are never added to an action diagram at print
time. If you would like action diagrams to be printed with
line numbers, choose the option on the format screen to add
the line numbers directly to the action diagram file. This is
the default choice, so you ordinarily get action diagrams (and
printouts) with line numbers. The restriction on adding line
numbers at print time prevents duplicate line numbers from
being printed.
The print section of SNAP! deals harshly with nonsense. For
example, if the sum of your left and right margins exceeds
your line width, SNAP! will set the line width and the margins
to their default values. Similarly, SNAP! will reject top and
bottom margins greater than page length, negative values, tab
expansions greater than 12 spaces, and so on.
SNAP! prints a three-line heading on each page of the
printout, showing program name, system name, copyright holder,
date, time, and page number. The heading begins on the line
immediately following the top margin you specify.
Accordingly, if you use a top margin of 8 and a bottom margin
of 8, with 66-line paper only 47 lines of code will be printed
on each page (66 lines - 8 top margin - 8 bottom margin - 3
heading).
For those of you with HP LaserJet II printers, try the
following parameters:
Line width: 132 Page length: 80
Top margin: 4 Bottom margin: 4
Left margin: 8 Right margin: 1
Setup string: \027E\027&l0o8D\027(10U\027(s16.6H
The \027E at the beginning of the string resets the printer.
SNAP! allows you to enter a setup string to configure the
printer for SNAP! (see above) and also a reset string to
configure the printer after SNAP! has completed printing. You
would not ordinarily need to enter a reset string, but you
42
might enter one if you wanted SNAP! to leave the printer
configured in a particular way.
When you are in the print options screen, you can press "F2--
List" to display a scrollable list of printer defaults. If
you select one of the printers shown, the choices associated
with it are used to update the print options parameters, such
as setup string, line width, page length and so forth. This
feature means that you don't have to remember complicated
control strings. You can define them in the print options
file and select them from the list.
The printer options are stored in SNAPPRT.SNP. It is an ASCII
file that you can edit to add more printer definitions.
Descriptions for how to add a printer are included at the top
of SNAPPRT.SNP.
Printing Without Documenting (Reprinting)
You can use the source code printing facilities of SNAP!
without going through the full time-consuming documentation
process. If you press the "F9--Print Now" key while viewing
the Print screen, SNAP! will prompt you for a filename
containing the names of files to print. SNAP! searches the
file you name and prints the contents of the files listed
therein. SNAP! will not print a file with an extension of
MEM, FRM, DBF, NDX, NTX, IDX, MDX, EXE, COM and other common
non-ASCII Dbase names. Also, SNAP! tries to figure out if a
particular file is not an ASCII file and warn you about it
before printing.
SNAP! will not try to print from anything that isn't a
filename, so the file you specify can contain all sorts of
garbage without causing a problem. The main effect of all
this is that you can give the Print routines the name of a
SNAP! REPRINT.DOC file and it will print all the source code
in the system without going through the full SNAP!
documentation process again. Of course, you can create your
own file containing filenames to print also. You can also use
this feature (and the DOCLIST.DOC file--just like REPRINT.DOC
excpet it holds the names of documentation files instead of
source code files) to print documentation files in a nicely
formatted way.
43
Using SNAP! in a Batch Environment
If you have several systems to document, you may wish to set
up a batch file to invoke SNAP! with the appropriate
parameters for each system so that you can come back in a week
or two and find all your programs beautifully documented.
SNAP! supports Immediate Mode for batch documentation through
the /X switch on the command line. Used in conjunction with
named configuration and macro files, you can sequentially
document a series of dBASE systems. SNAP! will take its input
from the configuration files (or from CONFIG.SNP if no
configuration file is named) and begin documenting the system
immediately. Note that you have to have your configuration
file ready before you invoke the system. If you do not
specify a configuration file, SNAP! tries to use CONFIG.SNP in
the current directory.
For example, to document three dBASE systems without pausing
for user input, set up a batch file with these lines:
SNAP /x /fsystem1.snp
SNAP /x /fsystem2.snp
SNAP /x
SNAP! will document the first system and take input from the
SYSTEM1.SNP configuration file. Then, without prompting for
further user action, it will read SYSTEM2.SNP and begin
documenting the second system. Input for the third system is
in the CONFIG.SNP (default name) file. When the batch file is
invoked, SNAP! will begin documenting and will not pause for
user input at any point in the process.
If an error occurs anywhere during the processing of these
three systems, SNAP! will display an error message and stop
documenting the system that experienced the error. The batch
file, however, will continue running and will move on to the
next system to be documented.
44
Random Notes
These are some other thoughts that don't seem to fit anywhere
else.
If you have a file named HELP.PRG in the program directory,
SNAP! assumes this must be a Clipper system, where 'HELP' is a
magic name and documents the program accordingly. SNAP!
treats HELP.PRG as if it were called directly from TopFile.
45
Program Limitations
and Things To Watch Out For
SNAP! had the following design limitations when this
documentation was written:
Maximum program files: 1024 programs, procedures
and functions
Maximum other files: 128 of each type
(e.g.databases)
Maximum variables: 2500 throughout the
system
Maximum key words: 1500 words
Maximum length of key word: 15 characters
Maximum length of a token: 20 characters
Maximum levels of program nesting: 20 levels
Maximum number of database fields: 1024 throughout the
system
Maximum length of filename: 67 characters
(including path)
These limitations were current when this documentation was
written. You can verify them (it would be a good idea) by
viewing the program limitations screen (Press F1 three times
from the greeting screen).
SNAP! uses about 210K of memory as "overhead." This much is
used as soon as the program is invoked. It also allocates
additional memory dynamically as it is needed. It is a memory
hog and will probably not be of much use if you don't have at
least 512K. Look at it this way: memory boards cost less than
commercial programs that compete with SNAP!. Don't look at
SNAP! as free software--look at it as an excuse to buy more
hardware.
Legal Coding that is Prohibited by SNAP!
I make no promises about what will happen if you run SNAP!
against invalid Dbase syntax, but predict that the results
will not be satisfying. On the other hand, there are some
"legal" coding techniques for Dbase that cause problems with
SNAP!. I have tried to keep these to a minimum, but some yet
remain.
You cannot use the word "END" as a variable in an assignment
statement of the form:
END = foo.
SNAP! sees the 'END' (which is a valid control structure
terminator in Clipper), treats anything else on the line as a
comment, and becomes powerfully confused. Using "END" in a:
STORE foo TO end
46
statement is acceptable. You also cannot use PROCEDURE or
FUNCTION (or a valid abbreviation of either) as a variable
name.
SNAP! does not track control structures across program or
procedure boundaries. Normally, this is not a problem since
you cannot start a DO WHILE loop in one program and finish it
in another. However, a BREAK statement can be in one program,
while the loop it is breaking out of is in another file.
Thus, SNAP! does not report an error when it sees a BREAK
statement, even if it cannot tell whether there is a loop for
the BREAK to apply to.
Hyphens in Filenames
SNAP! uses treats a hyphen as a delimiter when it is scanning
your source code to prepare the cross-reference report, since
the hyphen usually means "subtract." Thus, foo = bar-baz will
correctly generate three cross-references--one for "foo", one
for "bar" and one for "baz". This technique breaks down when
SNAP! sees "DO foo-bar." In this case, both "foo" and "bar"
will be cross-referenced. Note that SNAP! will find the right
file and continue documenting--it is only the cross-reference
report that is misleading.
Continuation Lines
Continuation lines may be a problem in some circumstances.
SNAP! actually reads each source file twice--once to check for
files and once to handle formatting (indentation,
capitalization, etc.) and cross-referencing. SNAP! tries to
deal with continuation lines during the first scan and so will
properly parse statements such as:
SET INDEX TO brlfq, foo, bar, ;
baz, plugh
and
SUM hatsize ;
FOR level = "MANAGEMENT"
(This latter statement led to particularly insidious effects
before continuation lines were parsed--SNAP! treated it as the
beginning of a FOR-NEXT control structure. This made for
interesting action diagrams.)
However, SNAP! cannot tell that:
abracadabra = ;
opensesame
47
is an assignment statement. Accordingly, the cross-reference
report will not contain the correct flag for an assignment
statement. While "abracadabra" and "opensesame" will properly
appear on the report, the proper cross-reference marker will
not be present.
Total line length, counting the length of continuation lines
but not leading and trailing white space, is limited to 255
characters. SNAP! warns you when it sees a longer line. This
is not a limitation on dBASE systems, since dBASE imposes the
same limit. FoxPro, Clipper and some other systems, however,
allow lines to exceed the 255-character limit. SNAP! reports
that it found a "line too long," ignores any bytes after the
255-character limit, and proceeds on its merry way.
There may be other anomalies related to continuation lines
that I have not thought of.
Multiple Procedure Files
If you use multiple procedure files and if they contain
procedures that have the same name, SNAP! may document your
system incorrectly. For example, assume you have two procedure
files that are SET at different points in the system. Both
files contain a procedure called FOO, but FOO is not the same
in each file. When SNAP! searches for procedures, it will
always find the first FOO and assume it is the one being
called. SNAP! does not track which procedure file is
currently active and cannot distinguish between
identically-named procedures in different procedure files.
This limitation has no effect on systems that use only one
procedure file, or on systems that have multiple procedure
files each containing uniquely-named procedures.
Giving different things the same name (this is my other
brother Daryl) is a bad programming habit to get into. It is
a good idea to use unique names for each procedure, function,
procedure file and program.
Suppressing Color
If you do not like the colors I selected, or if they do not
display properly on your monitor, putting the "/BW" switch on
the command line will disable color.
48
Change History
SNAP! has undergone several major changes. The following list
is not all-inclusive, but does hit the high points.
Changes From Version 3.0 to Version 4.0
Speed. Version 4.0 is about 25% faster than version 3.0 if
you have enough EMS memory to hold the 210K overlay. If not,
the speed of versions 4.0 and 3.0 will be approximately equal.
Memory Capacity. Version 4.0 uses program overlays to
increase the amount of memory available for cross referencing.
You will ordinarily get about 50K more memory with 4.0.
Dialect Support. SNAP! 4.0 now supports dBASE IV and FoxPro,
as well as all of the previously-supported variants of the
Dbase language.
Mouse Support. SNAP! 4.0 now fully supports mousing. You can
use the mouse to position the cursor, select function keys,
and do pretty much everything else you would expect.
Report Form and Label Documentation. If you are using dBASE
IV, SNAP! will automatically document the FRG and LBG files
that dBASE IV produces. These files are very much like
program files and contain the code to implement the reports or
labels you have defined. SNAP! will include these files in
the "CALLS" lists in the headings and will also include them
in the tree diagram if you have set the tree options to
display them. SNAP! does not produce the full report form
documentation for these files.
UDF Recognition. The code for detecting calls to user defined
functions (UDFs) has been extensively revised and should now
detect nearly all calls to UDFs, even the sneaky and
underhanded ones. For example, SNAP! now detects UDF calls
from MEMOEDIT, DBEDIT and ACHOICE in Clipper applications, as
well as a host of other, special, UDF situations.
Documentation of Other Files. Version 4.0 now tracks "other"
files--files that don't fit into any of the categories such as
databases, index files, etc. Examples of other files include
text files that are appended into memo fields, output files
from "SET PRINTER TO foo.txt" statements and so forth.
Printer Definition File. SNAP! 4.0 now is distributed with a
printer definition file, SNAPPRT.SNP, that contains parameters
for some common printers. It is an ASCII file and you can add
new printers (or variants of existing printers) to the list.
49
Parameters. SNAP! now displays function and procedures
parameters, if any, in the procedure summary. Each procedure
or function that takes a parameter will have the paramater
line displayed next to the function name in the Procedures
Summary report.
Page breaks. You can now use the "*# SNAP FORMFEED" directive
to force a page break at a specific spot in the source code.
The "*# SNAP FORMFEED" directive itself is not printed.
Program Narratives. SNAP! 4.0 supports program narratives if
they start with "*)" and echoes them to the HEADINGS.DOC file,
suitable for use as a cover page for each source code file.
Third-Party Libraries. SNAP! 4.0 is distributed with a set of
key words for several popular third-party function libraries.
You can instruct SNAP! to treat these key words as if they
were part of the language, which improves SNAP!'s handling of
capitalization, formating and other aspects of your
documentation.
PERSONAL.KEY. You can now create a file with your own set of
key words. "PERSONAL.KEY" is a magic name--SNAP! searches for
it in the SNAP! subdirectory and adds anything it finds in it
to the key words list.
"*# INCLUDE" key words. You can add a "*# INCLUDE foo"
statement to DB4WORDS.SNP or PERSONAL.KEY to include other key
words files, such as the third-party function library key
words described above.
Control Struture commenting. Version 4.0 also allows you to
add comments to the ends of control structures such as
IF/ENDIF and CASE/ENDCASE. For example, you can instruct
SNAP! to add the IF condition after each ENDIF.
IF foo = bar
DO this
ENDIF (foo = bar) <-- SNAP! adds the "(foo = bar)"
Reprinting source code. You can now run SNAP!, exit the
program without printing source code, and use the "F9--print
now" option to print the source code later. SNAP! now creates
a REPRINT.DOC file that contains the names of all programs,
procedures, action files and other files that are printed with
source code. Prior to version 4.0 it was difficult to print
source code if you did not do it during the SNAP!
documentation run. In addition, SNAP! creates the DOCLIST.DOC
file that contains the names of documentation files. You can
also use F9 to print these files.
50
Changes From Version 2.0 to Version 3.0
Speed. Version 3.0 is be approximately 2.5 times as fast as
version 2.0. The more procedures you use, the faster it will
be. SNAP! 2.0 was particularly inefficient in documenting
procedures.
Source Code Printing. You can now use the source code
printing routines without going through the entire
documentation process. When you press the right function key,
it asks for a filename. SNAP! searches this file for other
filenames, which it then prints.
User Interface. The user interface has gotten an
interface-lift <guffaw> since the last version. The number of
option screens grew too large to be conveniently browsed with
the facilities in version 2. Version 3 now organizes all the
screens underneath a main menu. You can also select menu
items with Alt-key combinations, without having to deal with
the menu itself.
Memory Usage. SNAP! 3.0 uses some additional dynamic data
structures to minimize wasted space. Under normal
circumstances, it should roughly triple the size of the
application that can be accommodated by the system. In
addition, after the conversion to Turbo Pascal 4.0, the size
of the program itself shrank by about 20%.
New Reports. A system summary is now available to show:
Lines of code
Database and index names
Number of program files
Number of procedures
. . . and lots of other summary information.
Arrays are recognized in the cross-reference report and are
denoted with brackets (for Clipper) or parentheses (for
FoxBASE), as appropriate (e.g., FOO[100] or FOO(100,50) ),
with the declared size shown. The cross-reference report also
lists public variables, macros and arrays separately.
The report form documentation has been revised extensively
(dBASE III only). It now shows each of the fields in the
report, displays the report heading, etc. Similar
documentation is now available for label forms, which were
ignored entirely by SNAP! version 2.0.)
The database summary now includes start and end columns for
each field. Alias names are now usually shown with the
appropriate physical database file in the data dictionary,
file heading, tree, etc.
51
Link files can now be created for PLINK86, Turbo C TLINK, or
the Microsoft LINK program. Make files continue to support
NDMAKE and now also support the Clipper MAKE utility.
File headings and may other reports show the date and time of
last change, based on the file date/time stamp.
Additional Options
Here are some of the new things you can control:
Suppression of blank lines in output file
Suppression of comments in output file
Optional extra indent under DO CASE statement
Inclusion of DBF, NDX, MEM, FRM and LBL files in the tree
Capitalization of key words
Capitalization of tokens
Temporary suspension of cross-referencing and formatting
Leave the file date/time stamp unchanged
Separate directories for programs and databases
Changes Since SNAP! Version 1.0
Practically everything.
52
Some Administrative Matters
Version Numbers
In the past, I have sometimes been criticized for releasing
one or more "maintenance" versions shortly after a major
update. I am guilty, but unrepentant. In an attempt to be
responsive to user suggestions and bug reports, I will
continue to add features and fix bugs as they are reported.
When the resulting minor changes are uploaded, the SNAP!
version will include a letter (e.g., SNAP! version 4.00 will
change to 4.00a). In this example, if you have version 4.00,
don't worry about downloading another version before 4.1
unless you need the specific features in the intervening
versions.
Updates and New Versions
SNAP! is available on Compuserve. At the time this
documentation file was written, copies are available on the
Nantucket forum and on the Ashton-Tate forum.
Rather than download the large SNAP! files, you may prefer to
send me a blank, formatted diskette (either 3.5 or 5.25 inch,
but 3.5 takes longer) and a postage-paid diskette mailer, and
I will send you the most current version. My address is:
Walter J. Kennamer
7027 Dunstans Lane
Toledo, Ohio 43617
If you want me to supply the mailers, disks and postage,
please enclose a check for $25. This high figure is
ostensibly for postage and handling, but is really for putting
me to the trouble of buying mailers, disks and stamps. I
prefer programming to managing a mailing effort, so I will do
the former cheaply but the latter only for a price.
How to Get Support
My CIS ID is 74025,514. I log on nearly every day, except
when I am traveling. I am easiest to reach through EasyPlex,
but I also check in on the Ashton-Tate, Nantucket and the PC
Vendors Forums periodically. If you have any suggestions
about how to improve SNAP! or if you have encountered a bug,
please let me know.
My job requires me to travel frequently, and I am usually hard
to reach by telephone. You will probably have better success
reaching me through Compuserve or by mail.
53
Association of Shareware Professionals
I am a member of the Association of Shareware Professionals
(ASP). ASP wants to make sure that the shareware principle
works for you. If you are unable to resolve a shareware-
related problem with an ASP member by contacting the member
directly, ASP may be able to help. The ASP Ombudsman can help
you resolve a dispute or problem with an ASP member, but does
not provide technical support for members' products. Please
write to the ASP Ombudsman at P.O. Box 5786, Bellevue, WA
98006 or send a Compuserve message via Easyplex to ASP
Ombudsman 70007,3536.
54
Acknowledgements
Special thanks to Andy Walsh for writing several string
procedures in assembly language for me. Thanks to Peter
Petto, Paul Ferrara and everyone else who helped me develop
and debug SNAP! Thanks to the Compuserve Nantucket SIG for
all the help its members gave me. Thanks to Dave Heindel for
helping me speed it up. Thanks to Pat Adams for public
relations.
Thanks to all the beta testers who helped so much with
handling the last-minute details. I used to mention them
separately. I don't anymore, though, so that they are not
blamed for any of the last-minute details that turn out not to
have been handled after all. They know who they are.
55
Appendix A -- Sample Reports
The following sample reports illustrate the formats of some
SNAP! output. Since the documentation for a full system is
voluminous, only limited portions of the documentation are
presented here. This saves much space, but has the
disadvantage of making some reports "out of sync." Thus, the
internal consistency of a complete package of documentation is
missing here. For example, if you try to trace the entries in
the tree back to TODO.PRG, you will discover that they don't
track since I trimmed out much of TODO.PRG so as to reduce the
bulk of the documentation file. Similarly, the system summary
shows a lot of databases that aren't in the DATADICT.DOC file.
Of course, the best way to see sample SNAP! reports is to run
it on some of your own programs.
56
*:*********************************************************************
*:
*: Program: TODO.PRG
*:
*: System: ToDo -- To Do Management System
*: Author: Walter J. Kennamer
*: Copyright (c) 1988, Walter J. Kennamer
*: Last modified: 02/26/88 23:00
*:
*: Calls: HELP.PRG
*: : F2_HANDLR (procedure in TODOPRC.PRG)
*: : HELPEDIT (procedure in TODOPRC.PRG)
*: : TDDEFLT.PRG
*: : ERRORMSG (procedure in TODOPRC.PRG)
*: : SETDATE.PRG
*: : TDLOGO.PRG
*: : TDSETUP.PRG
*: : TDINPUT.PRG
*:
*: Memory Files: ACCESSES.MEM
*: : DEFAULT.MEM
*:
*: Documented: 03/02/88 at 18:39 SNAP! version 3.00
*:*********************************************************************
PARAMETERS c_line && command line
*# SNAPMACRO s_tdfile todo
*# SNAPMACRO s_ddndx tododd
*# SNAPMACRO s0_adfname address
external subject
PUBLIC clipper,s_cmdline
IF pcount() > 0
s_cmdline = Alltrim(UPPER(c_line))
ELSE
s_cmdline = ""
ENDIF
.
.
.
* read defaults
USE
IF FILE("default.mem")
REST FROM DEFAULT ADDITIVE
IF s0_bw
s0_montype = "M"
ELSE
s0_montype = "C"
ENDIF
ELSE
DO tddeflt
ENDIF
DO tdinput
57
*: EOF: TODO.PRG
58
System Summary
System: ToDo -- To Do Management System
Author: Walter J. Kennamer
03/02/88 18:56:29
System Summary
-------------------------------------------------------------------------
This system has:
8636 lines of code
46 program files
2 procedure files
84 procedures and functions
18 databases
8 index files
3 report forms
0 format files
0 label forms
5 memory variable files
622 cross-referenced tokens
See the tree diagram for programs, procedures, functions and format files
Index Report Label Memory
Databases Files Forms Forms Files
-------------- -------------- -------------- -------------- -------------
HELP.DBF HELPKEY.NTX SUBREPT.FRM ACCESSES.MEM
TODO.SKL SUBJECT.NTX TDSUMIN.FRM DEFAULT.MEM
TODO.DBF TODODD.NTX TDDETIN.FRM LASTFILE.MEM
SUBJECT.DBF &NTXNAME PRINTER.MEM
ADDRESS.DBF HISTDD.NTX CLIP.MEM
&B_FILE.DBF PRIORITY.NDX
NOTEPAD.DBF DATEDUE.NDX
PRTCODES.DBF DATEDUE.NTX
&FILE
HIST.DBF
TEMP.DBF
&FNAME
&BAK_NAME.DBF
&FNAME.DBF
AREACODE.DBF
DATEDUE.DBF
PRM.SKL
ADDRESS.ASC
59
-------------------------------------------------------------------------
SNAP! created the following documentation files:
C:\SCRATCH\STATS.DOC
C:\SCRATCH\TREE.DOC
C:\SCRATCH\FILELIST.DOC
C:\SCRATCH\NDXSUMRY.DOC
C:\SCRATCH\DATADICT.DOC
C:\SCRATCH\FRMSUMRY.DOC
C:\SCRATCH\PRCSUMRY.DOC
C:\SCRATCH\XREF.DOC
C:\SCRATCH\TODO.LNK
C:\SCRATCH\TODO.TLK
C:\SCRATCH\TODO.MLK
C:\SCRATCH\MAKEFILE
C:\SCRATCH\ERROR.DOC
Action diagram files
UPDATE.BAT to update program source files in C:\TODO
BACKDBF.BAT to backup databases, indexes and memory files
BACKPRG.BAT to backup program files, report forms and format files
PRINTDOC.BAT to print documentation files
60
System: ToDo -- To Do Management System
Author: Walter J. Kennamer
03/02/88 18:56:09
Tree Diagram
-------------------------------------------------------------------------
TODO.PRG
├────HELP.PRG
│ │ HELP.DBF (database)
│ ├────SHOW_HELP (procedure in HELP.PRG)
│ │ ├────SETCOLOR (procedure in TODOPRC.PRG)
│ │ └────CENTER (procedure in TODOPRC.PRG)
│ ├────SETCOLOR (procedure in TODOPRC.PRG)
│ └────CENTER (procedure in TODOPRC.PRG)
├────F2_HANDLR (procedure in TODOPRC.PRG)
│ ├────ADDRLIST.PRG
│ │ └────SETCOLOR (procedure in TODOPRC.PRG)
│ └────NUMLIST.PRG
│ └────SETCOLOR (procedure in TODOPRC.PRG)
├────HELPEDIT (procedure in TODOPRC.PRG)
├────TDDEFLT.PRG
│ ├────SETCOLOR (procedure in TODOPRC.PRG)
│ ├────SCRHEAD (procedure in TODOPRC.PRG)
│ │ └────SETCOLOR (procedure in TODOPRC.PRG)
│ ├────TDSETUP.PRG
│ │ │ TODO.SKL (database)
│ │ │ TODO.DBF (database)
│ │ │ SUBJECT.DBF (database)
│ │ │ ADDRESS.DBF (database)
│ ├────CENTER (procedure in TODOPRC.PRG)
│ ├────SETDATE.PRG
│ ├────SETPRT.PRG
│ │ │ PRTCODES.DBF (database)
│ │ ├────SCRHEAD (procedure in TODOPRC.PRG)
│ │ │ └────SETCOLOR (procedure in TODOPRC.PRG)
│ │ └────ERRORMSG (procedure in TODOPRC.PRG)
│ │ ├────SETCOLOR (procedure in TODOPRC.PRG)
│ │ └────CENTER (procedure in TODOPRC.PRG)
│ ├────F2_HANDLR (procedure in TODOPRC.PRG)
│ │ ├────ADDRLIST.PRG
│ │ │ └────SETCOLOR (procedure in TODOPRC.PRG)
│ │ └────NUMLIST.PRG
│ │ └────SETCOLOR (procedure in TODOPRC.PRG)
│ ├────F3_HANDLR (procedure in TODOPRC.PRG)
and so forth
61
System: ToDo -- To Do Management System
Author: Walter J. Kennamer
03/02/88 18:55:52
Procedure and Function Summary
-------------------------------------------------------------------------
2 procedure files in the system
SUBJECT.PRG
TODOPRC.PRG
-------------------------------------------------------------------------
SUBJECT.PRG -- Last updated: 12/30/87 at 8:47
Contains: SUBOK() (Params: SUBNAME)
Calls: SETCOLOR (procedure in TODOPRC.PRG)
Calls: CENTER (procedure in TODOPRC.PRG)
Calls: PUTSUB (procedure in TODOPRC.PRG)
Contains: SUBLOOK() (Params: M_SUBNAME)
Calls: SETCOLOR (procedure in TODOPRC.PRG)
.
.
.
Contains: SUBEDIT (Params: none)
Called by: ED() (function in SUBJECT.PRG)
Calls: SETCOLOR (procedure in TODOPRC.PRG)
-------------------------------------------------------------------------
TODOPRC.PRG -- Last updated: 12/28/87 at 14:20
Contains: F2_HANDLR (Params: none)
Called by: TODO.PRG
Called by: TDDEFLT.PRG
Calls: ADDRLIST.PRG
Calls: NUMLIST.PRG
Contains: F3_HANDLR (Params: none)
Called by: TODO.PRG
Called by: TDDEFLT.PRG
Calls: SETCOLOR (procedure in TODOPRC.PRG)
Contains: F4_HANDLR (Params: none)
Called by: TODO.PRG
Called by: TDDEFLT.PRG
.
.
.
Contains: ISCTRL() (Params: none)
Contains: SCREEN_ON (Params: none)
Called by: ROLODEX.PRG
Contains: PRINT_ON (Params: none)
Called by: ROLODEX.PRG
62
System: ToDo -- To Do Management System
Author: Walter J. Kennamer
03/02/88 18:55:42
Database Structure Summary
-------------------------------------------------------------------------
3 databases in the system
HELP.DBF
TODO.DBF
SUBJECT.DBF
-------------------------------------------------------------------------
Structure for database : HELP.DBF
Number of data records : 37
Last updated : 09/09/87 at 11:06
Field Field name Type Width Dec Start End
1 HCALLPRG Character 8 1 8
2 HINPUTVAR Character 12 9 20
3 HSCRNNUM Character 4 21 24
4 HELPMSG Memo 10 25 34
** Total ** 35
This database is associated with the memo file: HELP.DBT
This database appears to be associated with index file(s):
: HELPKEY.NTX (UPPER(hcallprg+hscrnnum+hinputvar))
SNAP! did not find any associated report forms
Used by: HELP.PRG
: TDFIX.PRG
: TDREINDX.PRG
: TDREPAIR (procedure in TDFIX.PRG)
-------------------------------------------------------------------------
Structure for database : TODO.DBF
Number of data records : 112
Last updated : 03/01/88 at 17:35
Field Field name Type Width Dec Start End
1 ITEM Character 55 1 55
2 PRIORITY Character 1 56 56
3 DATE_DUE Date 8 57 64
4 CALTIME Character 5 65 69
5 COMPLETE Character 1 70 70
6 ADVANCE Numeric 3 71 73
7 DATE_ASGN Date 8 74 81
8 DATE_COMP Date 8 82 89
63
9 LATE Numeric 3 90 92
10 ITEMTYPE Character 1 93 93
11 ALARM Character 1 94 94
12 SUBJECT Character 30 95 124
13 DURATION Numeric 8 2 125 132
14 VERSION Character 5 133 137
** Total ** 138
This database appears to be associated with index file(s):
: TODODD.NTX (DTOS(date_due)+priority+caltime)
: DATEDUE.NDX (index key not found)
This database appears to be associated with multiple index file(s):
: TODO.MDX
SNAP! did not find any associated report forms
Used by: TDSETUP.PRG
: TDINPUT.PRG
: OPENDATA (procedure in TDSETUP.PRG)
: EDITEXIT.PRG
: TDREDATE.PRG
: TDPURGE.PRG
: TDFIX.PRG
: TDCAL.PRG
: TDREINDX.PRG
-------------------------------------------------------------------------
Structure for database : SUBJECT.DBF
Number of data records : 41
Last updated : 01/12/88 at 9:34
Field Field name Type Width Dec Start End
1 SUBCODE Character 20 1 20
2 SUBJECT Character 30 21 50
** Total ** 51
This database appears to be associated with index file(s):
: SUBJECT.NTX (UPPER(subject))
SNAP! did not find any associated report forms
Used by: TDSETUP.PRG
: TDINPUT.PRG
: OPENDATA (procedure in TDSETUP.PRG)
: TDREINDX.PRG
64
-------------------------------------------------------------------------
System: ToDo -- To Do Management System
Author: Walter J. Kennamer
03/02/88 18:55:49
Data Dictionary
-------------------------------------------------------------------------
Note: the actual system used more than 3 databases. All but three were
removed above to save space. This portion of the report shows all of
them.
Field Name Type Len Dec Database
ABBREV C 2 0 AREACODE.DBF
ADDRESS C 53 0 ADDRESS.DBF
ADVANCE N 3 0 TODO.SKL
TODO.DBF
HIST.DBF
ALARM C 1 0 TODO.SKL
TODO.DBF
HIST.DBF
AREACODE N 3 0 AREACODE.DBF
BPHONE C 12 0 ADDRESS.DBF
CALTIME C 5 0 TODO.SKL
TODO.DBF
HIST.DBF
CITIES C 78 0 AREACODE.DBF
CITY C 25 0 ADDRESS.DBF
COL N 2 0 PRTCODES.DBF
COMMENT C 50 0 ADDRESS.DBF
COMPANY C 53 0 ADDRESS.DBF
COMPLETE C 1 0 TODO.SKL
TODO.DBF
HIST.DBF
COMPRESS C 13 0 PRTCODES.DBF
COUNTRY C 20 0 ADDRESS.DBF
DATE_ASGN D 8 0 TODO.SKL
TODO.DBF
HIST.DBF
DATE_COMP D 8 0 TODO.SKL
TODO.DBF
HIST.DBF
DATE_DUE D 8 0 TODO.SKL
TODO.DBF
HIST.DBF
DURATION N 8 2 TODO.SKL
TODO.DBF
ELITE C 13 0 PRTCODES.DBF
FORMFEED C 13 0 PRTCODES.DBF
HCALLPRG C 8 0 HELP.DBF
HELPMSG M 10 0 HELP.DBF
HINPUTVAR C 12 0 HELP.DBF
HSCRNNUM C 4 0 HELP.DBF
65
ITEM C 55 0 TODO.SKL
TODO.DBF
HIST.DBF
ITEMTYPE C 1 0 TODO.SKL
TODO.DBF
HIST.DBF
LATE N 3 0 TODO.SKL
TODO.DBF
HIST.DBF
LINE C 78 0 TEMP.DBF
PRM.SKL
NAME C 30 0 ADDRESS.DBF
NAME C 25 0 PRTCODES.DBF
NOTES M 10 0 ADDRESS.DBF
NOTEPAD.DBF
PHONE C 12 0 ADDRESS.DBF
POSITION C 40 0 ADDRESS.DBF
PRIORITY C 1 0 TODO.SKL
TODO.DBF
HIST.DBF
PRTNUM N 2 0 PRTCODES.DBF
RESET C 13 0 PRTCODES.DBF
ROW N 2 0 PRTCODES.DBF
SECONDLINE C 53 0 ADDRESS.DBF
STATE C 2 0 ADDRESS.DBF
STATE C 15 0 AREACODE.DBF
SUBCODE C 20 0 SUBJECT.DBF
SUBJECT C 30 0 TODO.SKL
TODO.DBF
SUBJECT.DBF
HIST.DBF
VERSION C 5 0 TODO.SKL
TODO.DBF
NOTEPAD.DBF
ZIP C 10 0 ADDRESS.DBF
66
System: ToDo -- To Do Management System
Author: Walter J. Kennamer
03/02/88 18:55:15
Index Parameter Summary
-------------------------------------------------------------------------
5 index files in the system
HELPKEY.NDX
SUBJECT.NDX
TODODD.NDX
&NTXNAME
DATEDUE.NDX
-------------------------------------------------------------------------
HELPKEY.NTX -- Indexed on: UPPER(hcallprg+hscrnnum+hinputvar)
Last updated: 09/09/87 at 11:06
This index file appears to be associated with database(s):
: HELP.DBF
Used by: HELP.PRG
: TDFIX.PRG
: TDREINDX.PRG
: TDREPAIR (procedure in TDFIX.PRG)
-------------------------------------------------------------------------
SUBJECT.NTX -- Indexed on: UPPER(subject)
Last updated: 01/12/88 at 9:16
This index file appears to be associated with database(s):
: SUBJECT.DBF
Used by: SUBLOOK() (function in SUBJECT.PRG)
: PART_MATCH() (function in SUBJECT.PRG)
: TDSETUP.PRG
: TDINPUT.PRG
: OPENDATA (procedure in TDSETUP.PRG)
: TDFIX.PRG
: TDREINDX.PRG
: TDREPAIR (procedure in TDFIX.PRG)
-------------------------------------------------------------------------
TODODD.NTX -- Indexed on: DTOS(date_due)+priority+caltime
Last updated: 03/01/88 at 17:35
This index file appears to be associated with database(s):
: TODO.DBF
67
Used by: TDSETUP.PRG
: TDINPUT.PRG
: EDITEXIT.PRG
: EDITSRCH.PRG
: TDREDATE.PRG
: TDPURGE.PRG
: EDITCHGE.PRG
: TDFIX.PRG
: PRTUNCMP.PRG
: TDREINDX.PRG
: TDREPAIR (procedure in TDFIX.PRG)
-------------------------------------------------------------------------
&NTXNAME is a macro unknown to SNAP!
This index file appears to be associated with database(s):
: ADDRESS.DBF
Used by: TDSETUP.PRG
: OPENDATA (procedure in TDSETUP.PRG)
: ADDRESS.PRG
: TDFIX.PRG
: TDREINDX.PRG
: TDREPAIR (procedure in TDFIX.PRG)
: ADDRBOOK.PRG
: ROLODEX.PRG
-------------------------------------------------------------------------
File not found--DATEDUE.NDX
This index file appears to be associated with database(s):
: TODO.DBF
Used by: TDCAL.PRG
: TDCALDAY.PRG
68
System: ToDo -- To Do Management System
Author: Walter J. Kennamer
03/02/88 18:55:15
Multiple Index Summary
-------------------------------------------------------------------------
1 multiple index file in the system
TODO.MDX
-------------------------------------------------------------------------
TODO.MTX--Last updated: 09/09/87 at 11:06
TAG : TDITEM (item)
TAG : TDPRIOR (priority+itemtype)
This multiple index file appears to be associated with database(s):
: TODO.DBF
Used by: TODO.PRG
69
System: ToDo -- To Do Management System
Author: Walter J. Kennamer
03/02/88 18:55:50
Report Form File Summary
-------------------------------------------------------------------------
2 report forms in the system
SUBREPT.FRM
TDSUMIN.FRM
------------------------------------------------------------------------
SUBREPT.FRM Last updated: 08/24/87 at 10:14
Summary report? No
Eject page before printing? No Eject page after printing? Yes
Double space report? No Plain page? No
Left margin: 8 Right Margin: 0
-------------------------------------------------------------------------
Report Contents
-------------------------------------------------------------------------
No. Field Length Decimals Totaled?
--- ---------------------------------- ------ -------- --------
1 Subject 40 0 No
2 Subcode 25 0 No
-----
65
=====
-----------------------------------------------------------------------
Report Layout
-----------------------------------------------------------------------
Page No. 1
00/00/00
Subject Codes
Subject Charge Code
1 2
----------------------------------------------------------------------
Database and Program References
----------------------------------------------------------------------
SNAP! could not find an associated database
Used by: SUBREPT (procedure in SUBJECT.PRG)
70
TDSUMIN.FRM Last updated: 09/01/87 at 15:17
Summary report? No
Eject page before printing? Yes Eject page after printing? Yes
Double space report? Yes Plain page? No
Left margin: 1 Right Margin: 0
-------------------------------------------------------------------------
Report Contents
-------------------------------------------------------------------------
No. Field Length Decimals Totaled?
--- ---------------------------------- ------ -------- --------
1 "______" 6 0 No
2 RECNO() 4 0 No
3 Item 55 0 No
4 " "+dtoc(date_due) 9 0 No
5 Caltime 6 0 No
-----
80
=====
----------------------------------------------------------------------
Report Layout
----------------------------------------------------------------------
Page No. 1
00/00/00
Uncompleted Items
No. Item Due Date Time
=== =========================================== ========= =====
1 2 3 4 5
----------------------------------------------------------------------
Database and Program References
----------------------------------------------------------------------
SNAP! could not find an associated database
Used by: PRTUNCMP.PRG
71
System: ToDo -- To Do Management System
Author: Walter J. Kennamer
03/02/88 18:55:58
Token Cross-Reference Report
------------------------------------------------------------------------
622 tokens are included in this report.
Legend for context symbols:
(blank) reference does not change the variable or field value.
= variable or field is changed in an assignment statement.
x variable is released.
A array is declared.
G GET statement changes variable or field.
P variable is declared PUBLIC.
R field is replaced.
U database is USEd
V variable is declared PRIVATE.
& variable is referenced in a macro--takes preference over all others.
@ variable passed as a var parameter--Clipper only
? reference is of unknown type.
ABBREV
AREACODE.PRG 90 134 178
ABORT
TDINPUT.PRG 62x 67P 306=
EDITSRCH.PRG 35= 69= 99=
EDITCHGE.PRG 32=
ACCESSES
TODO.PRG 130
TDEXIT.PRG 24
.
.
.
YESNO
ADDRESS.PRG 476= 482G 482 484 663= 664 665= 668G 668
748= 751G 751 753
YR
TDCOPY.PRG 109= 116= 116 122 126 128 224 226 241=
248 255 262 264 277
ZIP
ADDRESS.PRG 130 227 282 301R 336R 363
ADDRBOOK.PRG 85 86 88
ROLODEX.PRG 180 181 183
72
73
System: ToDo -- To Do Management System
Author: Walter J. Kennamer
03/02/88 18:56:06
Public Variable Summary
------------------------------------------------------------------------
These variables were declared PUBLIC somewhere in the system.
Some may also be used as private variables in some parts of the code.
ABORT ADDR_MROW
ANSWER CARD_ROWS
CLIPPER CMD_LINE
C_OFFSET DATE_STR
.
.
.
S_TESTDATE S_VERSION
T_COMP T_DATED
T_DUR T_ITEM
T_ITEMTYPE T_PRIOR
T_SUBJ T_TIME
74
System: ToDo -- To Do Management System
Author: Walter J. Kennamer
03/02/88 18:56:06
Macro Summary
------------------------------------------------------------------------
Macros Defined to SNAP!
----------------------------------------------------------------------
Variable Expansion
-------------- ---------------------------------
S_TDFILE TODO
S_DDNDX TODODD
S0_ADFNAME ADDRESS
----------------------------------------------------------------------
Macros Not Defined to SNAP!
----------------------------------------------------------------------
&BAK_NAME &B_FILE
&COLR_STR &FIELD1
&FIELD2 &FIELD_NAME
&FILT_STR &FLDNAME
&FNAME &IN_DB
&IN_SELECT &IN_VAL
&M_WORKAREA &NTXNAME
&NUM &PROGNAME
&REP_FNAME &REV_COLR
&S0_COLR1 &S0_COLR2
&S0_DATA &S0_PRMNAME
&S0_PROGRAM &S0_USERFILT
&SRCHFLD &TEMPIN
------------------------------------------------------------------------
System: ToDo -- To Do Management System
Author: Walter J. Kennamer
03/02/88 18:56:06
Array Summary
------------------------------------------------------------------------
An array declared with a variable (e.g., DECLARE foo[bar])
will be shown as having a size of [var].
FIELD_LENGTH[var]
FIELD_LIST[2]
75
System: ToDo -- To Do Management System
Author: Walter J. Kennamer
03/02/88 18:56:29
File List
------------------------------------------------------------------------
Programs and procedures:
ADDRBOOK.PRG
ADDRESS.PRG
ADDRFILT() (function in ADDRESS.PRG)
ADDRLIST.PRG
.
.
.
TIMEFORM() (function in TDCALDAY.PRG)
TODO.PRG
UNHIGHLIGHT (procedure in SHOWCAL.PRG)
VERPRT.PRG
Procedure files:
SUBJECT.PRG
TODOPRC.PRG
Databases:
.
.
.
HELP.DBF
HELP.DBT
SUBJECT.DBF
TODO.DBF
Index files:
&NTXNAME
DATEDUE.NDX
DATEDUE.NTX
HELPKEY.NTX
HISTDD.NTX
PRIORITY.NDX
SUBJECT.NTX
TODODD.NTX
Report forms:
SUBREPT.FRM
TDDETIN.FRM
TDSUMIN.FRM
Memory files:
ACCESSES.MEM
CLIP.MEM
DEFAULT.MEM
76
Index
4PRINT . . . . . . . . . . . . . . . . . . . . . . . . 12, 13
Abbreviations . . . . . . . . . . . . . . . . . . . . . . . 9
Acknowledgements . . . . . . . . . . . . . . . . . . . . . 55
Action diagrams . . . . . . 2, 4, 7, 10, 12, 20, 38-42, 47, 60
User-defined symbols . . . . . . . . . . . . . . . . . . 41
Ashton-Tate . . . . . . . . . . . . . . . . . . . . . . 1, 53
Association of Shareware Professionals . . . . . . . . . . 54
Backup
Importance of . . . . . . . . . . . . . . . . . . . . . 6
Batch operation . . . . . . . . . . . . . . . . . . . . . . 44
Blank lines, suppression of . . . . . . . . . . . . . . . . 23
Break Statements . . . . . . . . . . . . . . . . . 21, 41, 47
Capitalization . 2, 5, 10, 18, 21-24, 34, 35, 40, 47, 50, 52
Change history . . . . . . . . . . . . . . . . . . . . . . 49
Clipper
Index files . . . . . . . . 11, 30, 43, 59, 63, 64, 67, 76
Command line switches
/A -- Alternate CASE indenting . . . . . . . . . . . . . 21
/BW -- black and white . . . . . . . . . . . . . . . . . 48
/F -- Configuration file name . . . . . . . . . . . . . 9
/M -- macro file name . . . . . . . . . . . . . . . . . 14
/O -- omit macros . . . . . . . . . . . . . . . . . . . 14
/S -- Echo reports to screen . . . . . . . . . . . . . . 26
/T -- SNAP! tag (changing *#) . . . . . . . . . . . . . 14
/X -- immediate mode (batch) . . . . . . . . . . . . . . 44
Comments
Putting them back in, design difficulties surrounding . 23
Suppression of . . . . . . . . . . . . . . . . . . . . . 23
Compuserve . . . . . . . . . . . . . . . . . . . . . . 53-55
CONFIG.SNP . . . . . . . . . . . . . . . . . . . . . . 9, 44
Configuration file . . . . . . . . . . . . . . . . 9, 41, 44
CONFIG.SNP . . . . . . . . . . . . . . . . . . . . . 9, 44
Retrieving configuration settings . . . . . . . . . . . 9
Saving configuration settings . . . . . . . . . . . . . 9
Continuation lines . . . . . . . . . . . . . . . . 3, 47, 48
Control structure . . . . . . . . . . . 20, 21, 39, 41, 46, 47
Cross-reference . . 2, 4, 5, 7, 10, 17, 18, 24, 26, 32-35, 42,
47, 48, 51, 60, 72
Key words . . . . . . . . . . . . . . . . . . . . . 23, 34
Legend . . . . . . . . . . . . . . . . . . . . . . . . . 33
Limitation of type flagging . . . . . . . . . . . . . . 34
Limiting to PUBLIC variables . . . . . . . . . . . . . . 35
Numeric constants . . . . . . . . . . . . . . . . . . . 33
Quoted strings excluded from . . . . . . . . . . . . . . 33
What is included . . . . . . . . . . . . . . . . . . . . 32
Data dictionary . . . . . . . . . . . 2, 4, 26, 28-30, 51, 65
dBASE II . . . . . . . . . . . . 1, 5, 7, 11, 24, 30, 31, 33
dBASE III . . . . . . . . 1, 5, 7, 11, 24, 30, 31, 35, 36, 51
dBASE IV 1, 5, 7, 8, 11, 24, 28, 31, 35, 36, 49
77
DBXL . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
DBxWORDS.SNP . . . . . . . . . . . . . . . . . . . 21, 22, 35
DB2WORDS.SNP . . . . . . . . . . . . . . . . . . . . 7, 24
DB3WORDS.SNP . . . . . . . . . . . . . . . . . . 7, 24, 35
DB4WORDS.SNP . . . . . . . . . . . . . . . . 7, 24, 25, 50
Documentation files
Printing . . . . . . . . . . . . . . . . . . . . . . . . 11
Elapsed time . . . . . . . . . . . . . . . . . . . . . . . 10
Errors . . . . . . . . . . . . . . 10, 21, 39, 40, 44, 47, 60
ERROR.DOC . . . . . . . . . . . . . . . . . . . . . 10, 60
Field names . . . . . . . . . . . . . . . . . . 22, 33, 63-65
Format files . . . . 2, 4, 8, 10, 15, 19, 27, 31, 37, 59, 60
Format screen . . . . . . . . . . . . . . 7, 20, 22-24, 40, 42
FoxBASE . . . . . . . . . . . 1, 5, 7, 11, 24, 30, 31, 35, 51
Index files . . . . . . . . . . . . . . . . . . 11, 30, 43
FoxPro . . . . . . . . . 1, 5, 7, 11, 24, 30, 31, 36, 48, 49
Functions
Capitalization of function names . . . . . . . . . . 24, 35
Hardware, why you should buy more . . . . . . . . . . . . . 46
Indentation . . . . . . . . . 2, 5, 10, 17, 18, 20, 21, 47, 52
Alternate CASE indenting . . . . . . . . . . . . . . . . 21
Index file . . 2, 4, 10, 11, 19, 28, 30, 38, 49, 59, 63, 64,
67-69, 76
NDX extensions . . . . . . . 30, 43, 52, 59, 64, 67, 68, 76
Input . . . . . . . . . . . . . . . . . 8, 11, 19, 33, 41, 44
Key words . . . . . . . . . 2, 7, 10, 18, 22-24, 33-35, 39, 46
Capitalization 2, 5, 10, 18, 21-24, 34, 35, 40, 47, 50, 52
Cross-referencing of . . . . . . . . . . . . . . . . 23, 32
DBxWORDS.SNP . . . . . . . . . . 7, 21, 22, 24, 25, 35, 50
Duplicates . . . . . . . . . . . . . . . . . . . . . . . 25
Expansion or compression . . . . . . . . . . . . . . . . 22
Including other files . . . . . . . . . . . . . . . . . 25
PERSONAL.KEY . . . . . . . . . . . . . . . . . . . . 24, 50
Peverse use of, punishment for . . . . . . . . . . . . . 9
Special characters in file . . . . . . . . . . . . . . . 23
Korenthal Associates . . . . . . . . . . . . . . . . . . . 12
Label forms . . . . . . . . . . . . 10, 19, 26-28, 51, 52, 59
License agreement . . . . . . . . . . . . . . . . . . . . . 1
Limitations . . . . . . . . . . . . . . . . . . . . . . . . 46
Link . . . . . . . . . . . . . . . . . . . . . . . 4, 36, 52
LINK.SNP . . . . . . . . . . . . . . . . . . . . . . . . 36
PLINK86 . . . . . . . . . . . . . . . . . . . . 4, 36, 52
MACRO.SNP . . . . . . . . . . . . . . . . . . . . . . . . . 14
Macros . . . 2, 8, 14-17, 19, 29, 34, 38, 44, 51, 68, 72, 75
SNAPMACRO . . . . . . . . . . . . . . . . . . . . . 14, 20
Make
Make files . . . . . 2, 4-7, 10, 20, 23, 36, 37, 46, 52, 54
MAKE.INI . . . . . . . . . . . . . . . . . . . . . . 36, 37
MAKEFILE . . . . . . . . . . . . . . . . . . . . . . 37, 60
NDMAKE . . . . . . . . . . . . . . . . . . . . . . . . . 36
Memory files . . 4, 8, 10, 15, 19, 26, 27, 32, 38, 57, 60, 76
Memory requirements . . . . . . . . . . . . . . . . . . . . 46
78
Nantucket . . . . . . . . . . . . . . . . . . . . . 1, 53, 55
Narratives . . . . . . . . . . . . . . . . . . . . . . . . 50
NDMAKE . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Other screen . . . . . . . . . . . . . . . . . . . . . 10, 11
Output . . . . 4, 6-8, 19, 20, 23, 24, 35, 37, 40, 49, 52, 56
Paths . . . . . . . . . . . . . . . . . 2, 6-9, 11, 15, 38, 46
PERSONAL.KEY . . . . . . . . . . . . . . . . . . . . . 24, 50
PLINK86 . . . . . . . . . . . . . . . . . . . . . . 4, 36, 52
LINK.SNP . . . . . . . . . . . . . . . . . . . . . . . . 36
Print screen . . . . . . . . . . . . . . . . . . . . . . . 43
HP LaserJet II setup string . . . . . . . . . . . . . . 42
Printer configuration file . . . . . . . . . . . . . . . . 26
Printing documentation . . . . . . . . . . . . . . . . . . 11
4PRINT . . . . . . . . . . . . . . . . . . . . . . . . . 12
Norton Utilities LP Program . . . . . . . . . . . . . . 12
Reprinting . . . . . . . . . . . . . . . . . . . 12, 43, 50
PRIVATE variables . . . . . . . . . . . . . . . 33-35, 72, 74
Procedure files
Unique name requirement . . . . . . . . . . . . . . . . 48
ProClip . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Program narratives . . . . . . . . . . . . . . . . . . . . 50
PUBLIC variables . . . . . . . 18, 33-35, 51, 55, 57, 72, 74
Quicksilver . . . . . . . . . . . . . . . . . . . . . . 5, 11
Recursion (see Recursion) . . . . . . . . . . . . . . . . . 27
Registration Fee . . . . . . . . . . . . . . . . . . . . . 5
Report forms 4, 8, 10, 19, 26-28, 31, 37, 59, 60, 63, 64, 70, 76
Rettig, Tom . . . . . . . . . . . . . . . . 18, 22, 24, 25, 35
SNAP FORMAT . . . . . . . . . . . . . . . . . . . . . . . . 18
SNAP XREF . . . . . . . . . . . . . . . . . . . . . . . . . 18
SNAP.DOC . . . . . . . . . . . . . . . . . . . . . . . . . 7
SNAP.EXE . . . . . . . . . . . . . . . . . . . . . . . . . 7
SNAP.HLP . . . . . . . . . . . . . . . . . . . . . . . . . 7
SNAP! directives
Changing *# . . . . . . . . . . . . . . . . . . . . . . 14
FORMAT . . . . . . . . . . . . . . . . . . . . . . . . . 18
SNAPCODE . . . . . . . . . . . . . . . . . . . 2, 15-18, 29
SNAPMACRO . . . . . . . . . . . . . . . . . 14-18, 29, 57
XREF . . . . . . . . . . . . . . . . . . . . . . . . . . 18
SNAPMACRO . . . . . . . . . . . . . . . . . . . . . . . 14, 20
Source code printout . . . . . . . . . . . . . . . . . . . 41
Alternatives to SNAP! . . . . . . . . . . . . . . . . . 11
Printing without documenting . . . . . . . . . . . . . . 43
What files are not printed . . . . . . . . . . . . . . . 43
Support, how to get . . . . . . . . . . . . . . . . . . . . 53
System screen . . . . . . . . . . . . . . . . . . . . 6, 9, 15
Tabs . . . . . . . . . . . . . . . . . . . . . 9, 20, 41, 42
Spaces instead of . . . . . . . . . . . . . . . . . . . 20
TLINK . . . . . . . . . . . . . . . . . . . . . . . 4, 36, 52
TopFile . . . . . . . . . . . . . . . 6-8, 10, 15, 32, 37, 45
Explanation of . . . . . . . . . . . . . . . . . . . . . 6
Tree screen . . . . . . . . . . . . . . . . . . . . . . . . 27
Turbo Linker . . . . . . . . . . . . . . . . . . . 4, 36, 52
79
Turbo Pascal . . . . . . . . . . . . . . . . . . . . . . . 51
Updates, how to get . . . . . . . . . . . . . . . . . . . . 53
Version Numbers . . . . . . . . . . . . . . . . . . . . . . 53
80